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

# Get a task

> Poll the status of an asynchronous image, video, or audio task.

Media generation that cannot finish inside one request becomes a task. This route
returns the current state of one task and, once it finishes, its result.

<Info>
  Video created through [`POST /v2/videos`](/api-reference/video/create) has its own
  envelope and its own poll route, [`GET /v2/videos/{id}`](/api-reference/video/get).
  Use this route for tasks created by the `/v1` media endpoints.
</Info>

<ParamField path="task_id" type="string" required>
  Task ID. PipeLLM-managed tasks start with `gen-`. The upstream provider's own task ID
  is also accepted for tasks that were created directly against a provider.
</ParamField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://api.pipellm.ai/v1/tasks/gen-1732891234-abc123xyz \
    -H "Authorization: Bearer $PIPELLM_API_KEY"
  ```

  ```python Python theme={"dark"}
  import os, time, requests

  headers = {"Authorization": f"Bearer {os.environ['PIPELLM_API_KEY']}"}

  while True:
      task = requests.get(
          f"https://api.pipellm.ai/v1/tasks/{task_id}", headers=headers
      ).json()

      if task["status"] in ("completed", "failed", "cancelled"):
          break
      time.sleep(3)

  print(task["status"], task.get("data"), task.get("error"))
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"dark"}
  {
    "id": "gen-1732891234-abc123xyz",
    "status": "processing",
    "type": "video_generation",
    "model": "seedance-2-0-mini",
    "created_at": "2026-09-17T08:14:02Z"
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string">
  Task ID. Use it on this route and on [cancel](/api-reference/tasks/cancel).
</ResponseField>

<ResponseField name="status" type="string">
  One of `pending`, `processing`, `completed`, `failed`, or `cancelled`.
</ResponseField>

<ResponseField name="type" type="string">
  `image_generation`, `image_edit`, `video_generation`, or `audio_generation`.
</ResponseField>

<ResponseField name="model" type="string">
  Model that is producing the result.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the task was created.
</ResponseField>

<ResponseField name="data" type="object">
  The result. Present once `status` is `completed`; its shape follows the task `type`.
</ResponseField>

<ResponseField name="error" type="string">
  Failure reason. Present when `status` is `failed`.
</ResponseField>

## Polling

A task moves `pending` → `processing` → one of `completed` / `failed` / `cancelled`.
Only those three are terminal; stop polling when you see one.

Poll every few seconds rather than in a tight loop — polls count against your
[rate limit](/api-reference/rate-limits), and polling faster does not make the
upstream finish sooner.

## Errors

Same envelope as [Errors](/api-reference/errors). An unknown ID returns `404`; a task
that belongs to another account is not visible to you and returns the same `404`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.