Skip to main content

​
Async Tasks and Workflows

Long-running operations (for example shading and energy model runs) are executed asynchronously.

​
Async Pattern

  1. Client submits a request to an async endpoint.
  2. API returns 200 with a taskId (and often created resource IDs).
  3. Worker processes the task.
  4. Client polls /tasks/{task_id} until terminal status.

​
Task Lifecycle

Task statuses:
  • pending
  • queued
  • running
  • completed
  • failed
  • cancelled
Stages provide finer progress (initializing, processing, saving, etc.).

​
Polling Endpoints

MethodPathPurpose
GET/tasksList tasks with optional filters (status, task_type, page, page_size).
GET/tasks/{task_id}Fetch status, progress, errors, and task result data.
POST/tasks/{task_id}/cancelCancel pending/queued/running tasks.

​
Workflow Chains

Some operations create a parent workflow with child tasks.
MethodPathPurpose
GET/workflows/{workflow_id}Return workflow parent + ordered child tasks.

​
Polling Example

curl -sS "$DALY_API_BASE_URL/tasks/1234" \
  -H "Authorization: Bearer $DALY_TOKEN"
Example response fields: 
{
  "id": 1234,
  "taskType": "energy_model",
  "status": "running",
  "progress": 60.0,
  "stage": "calculating",
  "resultData": null,
  "errorType": null,
  "errorMessage": null
}
Treat task result payloads as task-type-specific. For final model outputs, fetch the created resource directly (for example /energymodels/{id}).
For saved energy-model reruns, the queued task still resolves back to the same /energymodels/{id} row. Rerun does not create a second energy-model resource.