# Read tasks

Track durable media tasks and download successful outputs.

## GET `/api/generate/tasks/{id}`

Requires **read** scope. Returns `{task}` for a non-deleted public API media run owned by the account. Unknown, deleted, other-account, and non-public-API runs return `404 NOT_FOUND`. HEAD authenticates identically but has no response body.

## Response

The following is an illustrative successful response; IDs, Gem amounts, and URLs are examples.

```json
{
  "task": {
    "id": "airun_example",
    "status": "succeeded",
    "quotedGems": 10,
    "chargedGems": 10,
    "releasedGems": 0,
    "error": null,
    "outputs": [{
      "index": 0,
      "status": "succeeded",
      "asset": {
        "id": "asset_example",
        "kind": "image",
        "mimeType": "image/webp",
        "url": "https://SIGNED_OUTPUT_URL"
      }
    }]
  }
}
```

| Status | Client action |
| --- | --- |
| `queued` / `processing` | Keep the task ID and poll with backoff. |
| `succeeded` | Save the successful outputs. |
| `partial` | Save successful outputs and report failed outputs. |
| `failed` / `cancelled` | Stop polling and surface the sanitized error. |

Newly created/reserved runs appear as `queued`. Outputs may have `asset: null` while waiting or when no asset exists. `error` is either null or `{code, message}`. Do not assume that every terminal task has a downloadable asset.

## Polling and retention

Persist task IDs across reloads and process restarts. A practical polling schedule is 2, 4, 8, then 15 seconds with jitter, and a bounded application wait time. If your wait expires, retain the task for a later read instead of resubmitting it.

Signed media URLs can expire. Read the same task to obtain a current URL, then download immediately. Retain files you need; this API does not promise permanent output storage.

Task reads are read-only. They do not progress generation, settle billing, repair records, or copy media. No public task-cancellation or webhook-subscription endpoint is available. Text and extraction responses use same-request replay, not this media-task endpoint.