> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve a task
> GET /v1/contents/generations/tasks/{id} — poll a Seedance task for status, result, and the settled charge.
`GET /v1/contents/generations/tasks/{id}` returns the full task object. Poll it until `status` reaches a terminal state. The response body is **shape-identical to the native Seedance task object** — the same fields, with task ids as Aurous-native `vid_…` identifiers and two fields normalized back to what you sent (see [Normalization](#normalization)).
* **Scope:** `read`
* **Auth:** `X-Api-Key: al_live_…` or `Authorization: Bearer al_live_…`
```bash cURL theme={null}
curl https://api.aurous-labs.com/v1/contents/generations/tasks/vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP \
-H "X-Api-Key: al_live_…"
```
## Response
```json theme={null}
{
"id": "vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP",
"model": "seedance-2.0",
"status": "succeeded",
"error": null,
"created_at": 1731948000,
"updated_at": 1731948042,
"content": {
"video_url": "https://api.aurous-labs.com/v1/contents/generations/tasks/vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP/output?token=…",
"last_frame_url": "https://api.aurous-labs.com/v1/contents/generations/tasks/vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP/output/last_frame?token=…"
},
"seed": 123456,
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"framespersecond": 24,
"generate_audio": true,
"safety_identifier": "your-original-value",
"priority": 0,
"draft": false,
"draft_task_id": null,
"service_tier": "online",
"execution_expires_after": 172800,
"usage": {
"completion_tokens": 108000,
"total_tokens": 108000
}
}
```
### Fields
| Field | Type | Notes |
| --------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | The `vid_…` task id. |
| `model` | string | The canonical model id you targeted (normalized). |
| `status` | enum | See [Status](#status). |
| `error` | object \| null | `{ "code", "message" }` on a failed task; `null` otherwise. |
| `created_at` / `updated_at` | integer | Unix seconds. |
| `content` | object | `{ "video_url", "last_frame_url"? }` on success. Both are **Aurous streaming URLs** — the bytes are proxied through Aurous, so they point at Aurous endpoints (`…/v1/contents/generations/tasks/{id}/output[/last_frame]?token=…`), never an upstream storage host. Valid **\~24 h** — download what you want to keep. `last_frame_url` present only if you passed `return_last_frame: true`. |
| `seed` | integer | Seed the model selected. Returned only — `seed` is **not** a settable input on the 2.0 family (see [Create a task → parameters](/api-reference/seedance/create-task#parameters)). |
| `resolution` | string | Output resolution. |
| `ratio` | string | Output aspect ratio. |
| `duration` **or** `frames` | integer | The delivered length. One of the two is present. |
| `framespersecond` | integer | Output frame rate (24 for this family). |
| `generate_audio` | boolean | Whether an audio track was generated. |
| `safety_identifier` | string | **Your original value**, echoed back unchanged (see [Normalization](#normalization)). |
| `priority` | integer | Queue priority you set. |
| `draft` / `draft_task_id` | boolean / string | Draft-mode fields (not used by the 2.0 family). |
| `service_tier` | string | `online` for this family. |
| `execution_expires_after` | integer | Seconds the task may sit before expiring. |
| `usage` | object | `{ "completion_tokens", "total_tokens" }`. **This is the billing basis** — see [Billing](#billing). For video models input tokens are always 0, so `total_tokens == completion_tokens`. |
## Status
| `status` | Terminal? | Meaning |
| ----------- | --------- | --------------------------------------------------------------------------------------- |
| `queued` | no | Accepted, waiting for a worker. |
| `running` | no | Generating. |
| `succeeded` | yes | Done. `content.video_url` is populated. |
| `failed` | yes | Generation failed. `error` carries the reason. Charged **0**. |
| `expired` | yes | Task sat past `execution_expires_after` and was expired by the provider. Charged **0**. |
| `cancelled` | yes | You cancelled it while queued. Charged **0** (full refund). |
Poll until `status` is one of the four terminal values. A comfortable interval is \~10–15 seconds; a queued task may sit for a while (up to your `execution_expires_after`), so back off rather than hammering. A task whose `content` includes a person reference can spend a little extra time in `queued` while that reference is prepared — no different to poll for.
## Billing
Billing on the raw surface is **hold-then-settle**, and rides on headers — the body is never modified.
1. **On create**, a **credit ceiling is held** and reported on `Aurous-Credits-Held`.
2. **At success**, the charge **settles on `usage.completion_tokens`** — the actual metered tokens the provider reports. The settled amount appears on the `Aurous-Credits-Charged` header of a terminal retrieve, and as a line item in [`GET /v1/usage`](/api-reference/openapi#tag/usage).
3. **You are charged only on success.** `failed`, `expired`, and (queued) `cancelled` tasks charge **0** and release the hold in full.
| Header (terminal retrieve) | Meaning |
| -------------------------- | -------------------------------------------------------------- |
| `Aurous-Credits-Charged` | The exact credits deducted (present once `status: succeeded`). |
| `Aurous-Request-Id` | Correlation id for support. |
When you pass an explicit `duration`, a fixed `ratio`, and no reference video,
the held ceiling **equals the final charge exactly** — there is nothing to
reconcile. For a **video-input** task the hold assumes the maximum 15 s of
reference footage (we never fetch your clip to measure it), so the held ceiling
is an **upper bound** and the settled charge is typically lower. See
[Models & pricing](/api-reference/seedance/models-and-pricing) for the full math.
## Normalization
Two fields are restored to what you sent, so the response reflects your own inputs:
* **`model`** — returned as the canonical model id/alias you targeted.
* **`safety_identifier`** — returned as your original value (it is namespaced per team upstream for abuse attribution, then restored on the way out).
Everything else in the task object is the provider's, verbatim.
## Read-through and retention
* **Non-terminal tasks** are read live from the provider on each retrieve, so you always see the current status.
* **Terminal tasks** are served from Aurous's stored copy.
**Retention delta.** Aurous keeps your task records queryable **past the
provider's 7-day history purge** — a superset of the native API. The
`video_url` and `last_frame_url` are **Aurous streaming URLs** (the bytes are
proxied through Aurous), and they still **expire \~24 hours after the video was
generated**, so the record remains readable but its media links go stale.
Download what you want to keep.
## Errors
| Code | HTTP | When |
| -------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](/errors#resource_not_found) | 404 | Unknown id, another team's task, or a deleted task. Indistinguishable by design (no cross-team leakage). |
| [`insufficient_scope`](/errors#insufficient_scope) | 403 | The API key lacks the `read` scope. |
A `vid_…` id that belongs to a non-raw generation is not addressable here and returns `404` — the raw surface and the [`/v1/videos`](/api-reference/videos/create-video) surface never cross-resolve ids.