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

# Get task status

> One endpoint to check any asynchronous generation task by its ID.

Query any asynchronous task (video generation today) with the task ID returned
when you submitted it.

<ParamField path="id" type="string" required>
  The task ID returned when you submitted the request, for example
  `task_01HXYZ`.
</ParamField>

## Response fields

<ResponseField name="id" type="string">
  The task ID you submitted.
</ResponseField>

<ResponseField name="status" type="string">
  `queued`, `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="model" type="string">
  The model that ran the task.
</ResponseField>

<ResponseField name="progress" type="number">
  0–100.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp (seconds) of submission.
</ResponseField>

<ResponseField name="completed" type="number | null">
  Unix timestamp (seconds) of completion. `null` while running.
</ResponseField>

<ResponseField name="cost" type="number">
  Amount billed in USD. Failed tasks are automatically refunded.
</ResponseField>

<ResponseField name="result" type="object | null">
  Present when `status` is `completed`. `result.videos[].url` is an array of
  direct download URLs (some models return more than one file);
  `result.videos[].expires_at` is the Unix timestamp when the URLs stop
  working.
</ResponseField>

<ResponseField name="error" type="object | null">
  `error.message` holds the failure reason when `status` is `failed`.
</ResponseField>

<Warning>
  Result URLs expire (media is retained for 14 days — see `expires_at`).
  Download the files to your own storage promptly.
</Warning>

Poll every 10 to 20 seconds, or skip polling entirely with a
[webhook](/api-reference/webhooks) — the webhook payload is exactly this
response object.

<RequestExample>
  ```bash Curl theme={null}
  curl https://api.snapgen.org/v1/tasks/task_01HXYZ \
    -H "Authorization: Bearer $SNAPGEN_API_KEY"
  ```

  ```python Python theme={null}
  import json
  import os
  from urllib.request import Request, urlopen

  request = Request(
      "https://api.snapgen.org/v1/tasks/task_01HXYZ",
      headers={"Authorization": f"Bearer {os.environ['SNAPGEN_API_KEY']}"},
  )

  with urlopen(request) as response:
      task = json.load(response)

  print(task["status"], task.get("result"))
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.snapgen.org/v1/tasks/task_01HXYZ",
    { headers: { Authorization: `Bearer ${process.env.SNAPGEN_API_KEY}` } },
  );
  const task = await response.json();
  console.log(task.status, task.result);
  ```
</RequestExample>

<ResponseExample>
  ```json Completed theme={null}
  {
    "id": "task_01HXYZ",
    "object": "task",
    "status": "completed",
    "model": "gemini-omni-t2v",
    "progress": 100,
    "created": 1784324432,
    "completed": 1784324660,
    "cost": 0.25,
    "result": {
      "videos": [
        {
          "url": ["https://storage.example.com/videos/output.mp4"],
          "expires_at": 1785534260
        }
      ]
    },
    "error": null
  }
  ```

  ```json Failed theme={null}
  {
    "id": "task_01HXYZ",
    "object": "task",
    "status": "failed",
    "model": "gemini-omni-t2v",
    "progress": 100,
    "created": 1784324432,
    "completed": 1784324655,
    "cost": 0,
    "result": null,
    "error": { "message": "Upstream generation failed" }
  }
  ```

  ```json In progress theme={null}
  {
    "id": "task_01HXYZ",
    "object": "task",
    "status": "in_progress",
    "model": "gemini-omni-t2v",
    "progress": 30,
    "created": 1784324432,
    "completed": null,
    "cost": 0.25,
    "result": null,
    "error": null
  }
  ```
</ResponseExample>