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

# Get Task Status

> Retrieve the status and result of any async task using the poll_url returned by create endpoints

## Overview

Use this endpoint for unified async polling across task types such as video, image, music, and 3D generation.

If a create response includes `poll_url`, call that exact path. Some image models may return task-based responses under either an image-specific status path or `/v1/tasks/{id}`.

## Path Parameters

<ParamField path="id" type="string" required>
  The task ID returned by the create request.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Canonical async task identifier.
</ResponseField>

<ResponseField name="task_id" type="string">
  Async task identifier alias.
</ResponseField>

<ResponseField name="poll_url" type="string">
  Preferred polling URL when the create response supplies one.
</ResponseField>

<ResponseField name="status" type="string">
  Task status such as `pending`, `processing`, `completed`, or `failed`. Cancelled tasks are represented as `failed` with `cancelled: true`.
</ResponseField>

<ResponseField name="cancelled" type="boolean">
  `true` when a queued async task was cancelled before execution.
</ResponseField>

<ResponseField name="cancellation_status" type="string">
  Cancellation marker. Present as `cancelled` when cancellation succeeds.
</ResponseField>

<ResponseField name="data" type="array">
  For completed image tasks, generated image results are returned here. Image tasks return URLs in `data[].url`.
</ResponseField>

<ResponseField name="progress" type="number">
  Optional progress value. Returned only when a real progress value is available; use `status` to determine completion.
</ResponseField>

<ResponseField name="video_url" type="string">
  Result asset URL when the task completes and produces a video.
</ResponseField>

<ResponseField name="video" type="object">
  Single video payload with `url`, `duration`, `width`, and `height` when available.
</ResponseField>

<ResponseField name="videos" type="array">
  Multiple video payloads when more than one output is available.
</ResponseField>

<ResponseField name="error" type="string">
  Error message when the task fails.
</ResponseField>

<ResponseField name="created" type="integer">
  Creation timestamp when available.
</ResponseField>

<ResponseField name="updated" type="integer">
  Last update timestamp when available.
</ResponseField>

<ResponseField name="model" type="string">
  Model used by the task when available.
</ResponseField>

## Error Behavior

If the task no longer exists, has expired, or is no longer available in the public task record, TokenLab returns:

```json theme={null}
{
  "error": {
    "message": "Task not found or no longer available.",
    "type": "invalid_request_error",
    "code": "async_task_not_found"
  }
}
```

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
    -H "Authorization: Bearer sk-your-api-key"
  ```
</RequestExample>

```python Python theme={null}
import requests

poll_url = "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
response = requests.get(
    f"https://api.tokenlab.sh{poll_url}",
    headers={"Authorization": "Bearer sk-your-api-key"},
)
print(response.json())
```

```javascript JavaScript theme={null}
const pollUrl = '/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
const response = await fetch(`https://api.tokenlab.sh${pollUrl}`, {
  headers: { Authorization: 'Bearer sk-your-api-key' },
});
console.log(await response.json());
```