# Query video generation task status

Poll the current status of a video generation task.

- **queued**: Queued. Continue polling (recommended interval: 5-10 seconds).
- **processing**: Generating. Continue polling.
- **succeeded**: Generation complete. The `video_url` field contains a downloadable video link (expiry is reported by video_url_expires_at).
- **failed**: Generation failed. The `error` field contains the error message. Frozen amount is automatically refunded.
- **expired**: Task timed out (exceeded the `execution_expires_after` setting).
- **cancelled**: Task was cancelled (via DELETE endpoint for queued tasks).

Task records are retained for 7 days and automatically purged after that.

## GET /v1/videos/generations/{taskId}

> Query video generation task status

Poll the current status of a video generation task.

- **queued**: Queued. Continue polling (recommended interval: 5-10 seconds).
- **processing**: Generating. Continue polling.
- **succeeded**: Generation complete. The `video_url` field contains a downloadable video link (expiry is reported by video_url_expires_at).
- **failed**: Generation failed. The `error` field contains the error message. Frozen amount is automatically refunded.
- **expired**: Task timed out (exceeded the `execution_expires_after` setting).
- **cancelled**: Task was cancelled (via DELETE endpoint for queued tasks).

Task records are retained for 7 days and automatically purged after that.

### Authentication

`Authorization: Bearer tr-xxx`

### Path Parameters

- **taskId** `string` **(required)**  
  Task ID (the `id` field returned by `POST /v1/videos/generations`)

### Query Parameters

- **video_url_mode** `string`  
  One-time result view; does not change the task or webhook policy.

### Response

- **id** `string` **(required)**  
  Platform internal task ID
- **model** `string` **(required)**  
  Model ID used
- **status** ``queued` | `processing` | `succeeded` | `failed` | `expired` | `cancelled`` **(required)**  
  Task status
- **video_url_source** ``upstream` | `tos``  
  
- **video_url_expires_at** `string`  
  Null means unknown expiry, not permanent.
- **generation_status** `string`  
  Independent generation state. tos may report processing while generation_status is succeeded.
- **delivery_status** ``ready` | `pending` | `failed` | `expired``  
  
- **result_query_path** `string`  
  Authenticated result lookup path, including in delayed callbacks.
- **storage** `object`  
  
- **storage.status** ``pending` | `transferring` | `ready` | `failed` | `expired``  
  
- **storage.video_url** `string`  
  
- **storage.last_frame_url** `string`  
  
- **video_url** `string`  
  Download URL for the generated video (valid for 24 hours). Only present when `status: succeeded`
- **last_frame_url** `string`  
  Last frame image URL (PNG, valid for 24 hours). Only returned when `return_last_frame: true` was set at creation and `status: succeeded`
- **duration** `integer`  
  Duration of the generated video (seconds). Mutually exclusive with `frames`
- **frames** `integer`  
  Number of frames in the generated video. Only returned when `frames` parameter was specified at creation (mutually exclusive with `duration`)
- **resolution** `string`  
  Resolution of the generated video
- **ratio** `string`  
  Aspect ratio of the generated video
- **seed** `integer`  
  Actual random seed value used for this request
- **generate_audio** `boolean`  
  Whether the generated video includes synchronized audio (only returned for Seedance 2.0, 1.5 pro)
- **service_tier** `string`  
  Actual service tier used
- **draft** `boolean`  
  Whether this task is a draft preview. True when a Seedance 2.5 draft succeeds. The 1080p final video generated from a draft is false or omitted.
- **usage** `object`  
  Token usage for this request. Only present when `status: succeeded`
- **usage.completion_tokens** `integer`  
  Tokens consumed by the model for video output
- **usage.total_tokens** `integer`  
  Total tokens (video generation models do not count input tokens, so total = completion)
- **error** `object`  
  Error information. Only present when `status: failed`
- **error.code** `string`  
  Error code
- **error.message** `string`  
  Error description
- **result** `object`  
  Complete raw response from the upstream provider. Only present when `status: succeeded`
- **created_at** `string` **(required)**  
  Task creation time
- **updated_at** `string` **(required)**  
  Task last updated time

### Error Codes

- `401`: 
- `404`: Task not found or does not belong to the current user
- `409`: Generation succeeded but delivery is unavailable. Inspect storage or query with video_url_mode=tos; this is not a generation refund.
- `410`: Native URL has expired. Query with video_url_mode=tos to retrieve a saved copy.
- `429`: