> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dalyenergy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Tasks and Workflows

> How DalyAPI queues long-running jobs and reports progress

# 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

| Method | Path                      | Purpose                                                                        |
| ------ | ------------------------- | ------------------------------------------------------------------------------ |
| `GET`  | `/tasks`                  | List 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}/cancel` | Cancel pending/queued/running tasks.                                           |

## Workflow Chains

Some operations create a parent workflow with child tasks.

| Method | Path                       | Purpose                                       |
| ------ | -------------------------- | --------------------------------------------- |
| `GET`  | `/workflows/{workflow_id}` | Return workflow parent + ordered child tasks. |

## Polling Example

```bash theme={null}
curl -sS "$DALY_API_BASE_URL/tasks/1234" \
  -H "Authorization: Bearer $DALY_TOKEN"
```

Example response fields:

```json theme={null}
{
  "id": 1234,
  "taskType": "energy_model",
  "status": "running",
  "progress": 60.0,
  "stage": "calculating",
  "resultData": null,
  "errorType": null,
  "errorMessage": null
}
```

<Info>
  Treat task result payloads as task-type-specific. For final model outputs, fetch the created resource directly (for example `/energymodels/{id}`).
</Info>

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.