# Tasks & polling

> Understand the task lifecycle, synchronous waiting, polling, cancellation, and result retention.

## Task lifecycle

Every generation request creates a task object (`object: "task"`) that moves through a fixed set of states:

- `queued`: Accepted and funds held; waiting to start. Only `queued` tasks can be canceled.
- `running`: Actively generating.
- `succeeded`: Terminal state. Outputs appear in `output` and `cost.status` is `"settled"`.
- `failed`: Terminal state. Error details appear in `error` and `cost.status` is `"refunded"`.
- `canceled`: Terminal state. Canceled while `queued`; `cost.status` is `"refunded"`.

## Synchronous wait vs. polling

For fast image models, pass `wait_seconds` (1–60) on `POST /v1/tasks` so the request waits until the task finishes or the timeout elapses. For video models or longer runs, submit with `wait_seconds: 0` (the default) and either receive a [Webhook](/docs/webhooks) or poll `GET /v1/tasks/{id}` every 2–5 seconds.

```bash
curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \
  -H "Authorization: Bearer $KEROX_API_KEY"
```
```python
import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"}
task_id = "task_01JD8X9B4Q2M7T8N3K5P6R1S0V"

while True:
    task = requests.get(
        f"https://api.kerox.ai/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] in ("succeeded", "failed", "canceled"):
        print(task)
        break
    time.sleep(3)
```
```javascript
const headers = { Authorization: `Bearer ${process.env.KEROX_API_KEY}` };
const taskId = 'task_01JD8X9B4Q2M7T8N3K5P6R1S0V';

while (true) {
  const res = await fetch(`https://api.kerox.ai/v1/tasks/${taskId}`, { headers });
  const task = await res.json();
  if (['succeeded', 'failed', 'canceled'].includes(task.status)) {
    console.log(task);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
```

## Listing & canceling tasks

- **List tasks**: `GET /v1/tasks?status=succeeded&model=bytedance/seedance-2.5&limit=20&cursor=...` returns your tasks newest first, across API, Studio, and MCP. Filter with `status`, `model`, and `source`; `limit` is 1–100 (default 20). When `has_more` is `true`, pass `next_cursor` as `cursor` for the next page.
- **Cancel a queued task**: `POST /v1/tasks/{id}/cancel` cancels a `queued` task and immediately refunds the hold. If the task is already `running` or finished, the API returns HTTP `409` (`task_not_cancelable`).

## Metadata, timeouts & retention

- **Metadata**: Attach up to 4 KB of arbitrary JSON in `metadata` (for example `{"order_id": "A1001"}`); it is returned verbatim on queries and webhooks.
- **Timeouts**: Image tasks time out after 10 minutes and video tasks after 60 minutes by default (exact per-model limit is `timeout_seconds` in `GET /v1/models/{id}`). Timed-out tasks fail with `timeout` and refund in full.
- **Retention**: Generated files expire 7 days after completion (`expires_at`). Task metadata and ledger entries are kept permanently.
