---
title: "Get a task"
description: "Reads a task created by any v2 endpoint. Poll it every few seconds until status is completed, failed or cancelled."
canonical: "https://platform.pixai.art/en/docs/api-v2/task/getTask"
last-updated: "2026-11-02"
---

# Get a task

Reads a task created by any v2 endpoint. Poll it every few seconds until `status` is `completed`, `failed` or `cancelled`.



Where the result is:

* Images (`taskKind` `t2i`, `i2i`, `inpaint`): `outputs.mediaIds` and `outputs.mediaUrls`.
* Videos (`taskKind` `i2v-inhouse`, `reference-video`): `outputs.videoMediaId`. Resolve it with `GET /v2/media/batch?ids=<videoMediaId>` and download `fileUrl`. `outputs.mediaIds` then holds only the poster image.

Generated media is not kept forever. Download results soon after they finish.

## GET https://api.pixai.art/v2/task/{id}

Authentication: send your API key as `Authorization: Bearer <API key>`.

Machine-readable OpenAPI spec: https://platform.pixai.art/openapi-spec.v2.yaml

### Parameters

- `id` (in path, string, required)
  The task ID.
- `with_parameters` (in query, string, optional)
  Send `true` to include the stored task parameters in `parameters`.
  Allowed values: `true`.

### Example (cURL)

```bash
curl https://api.pixai.art/v2/task/1943547603237249965 \
  -H "Authorization: Bearer $PIXAI_API_KEY"
```

### Responses

- `200`
  The task.
  Body fields:
  - `id` (string, required)
    The unique identifier for the task.
  - `status` (string, required)
    The current status of the task.
    Allowed values: `waiting`, `running`, `completed`, `cancelled`, `failed`.
  - `createdAt` (string, required)
    The time the task was created.
  - `updatedAt` (string, required)
    The time the task was last updated.
  - `startedAt` (string, optional)
    The time the task started running.
  - `endAt` (string, optional)
    The time the task finished.
  - `taskKind` (string, optional)
    What the task makes: `t2i` or `i2i` for images, `inpaint` for `POST /v2/gen-task/inpaint`, `i2v-inhouse` for `POST /v2/frame-video/create`, `reference-video` for `POST /v2/reference-video/create`.
  - `paidQuota` (integer, optional)
    Credits charged for the task.
  - `taskStatusMsgI18n` (object, optional)
    Why a `failed` task failed.
  - `taskStatusMsgI18n.key` (string, optional)
    A stable message key.
  - `taskStatusMsgI18n.defaultMessage` (string, optional)
    The message in English.
  - `outputs` (object, optional)
    The outputs produced by the task.
  - `outputs.videoMediaId` (string, optional)
    For video tasks, the media ID of the video. Resolve it with `GET /v2/media/batch?ids=<videoMediaId>` and download `fileUrl`. `mediaIds` then holds only the poster image.
  - `outputs.seed` (string, optional)
    The seed used, as a decimal string.
  - `outputs.mediaIds` (string[], optional)
    Media IDs of the generated images. Use these IDs to fetch detailed information about each generated image.

    Generated images are not permanently retained — retrieve them as soon as possible.
  - `outputs.mediaUrls` ((string | null)[], optional)
    Public URLs of the generated images.

    Generated images are not permanently retained — retrieve them as soon as possible. If an image is unavailable, its entry may be `null`.
- `401`
  `UNAUTHORIZED`: no API key was sent. An invalid, revoked or expired key answers `{"message": "invalid token", "code": 40100001}` instead, with a numeric `code`.
- `404`
  `NOT_FOUND`: no task with this ID is visible to you. A request without an API key gets this for every task.