Tasks

Get task status

Query an owned generation task and read its status, credit accounting, outputs or failure.

Endpoint

GET/api/v1/developer/generations/{generation_id}

Authentication & scope

Authorization: Bearer <credential>; formal account API Key / OAuth only.

Scope: generations:read

Only the current App and credential owner's tasks are accessible. Respect poll_after_ms for nonterminal tasks; stop on succeeded, failed or cancelled. Nullable fields are omitted and formal responses do not include anonymous quota.

Request parameters

Field	Type	Required	Description
`generation_id`	UUID (path)	Yes	Identifier returned when creating the task; no request body.

curl --request GET \
  --url 'https://api.perchanceai.art/api/v1/developer/generations/{generation_id}' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>'

Response HTTP 200

Illustrative response shape, not a live API response. Example numbers and USD do not imply fixed pricing or a cash balance. Null fields are omitted.

REST success responses contain success, code, message, request_id and data; the table describes data.

Field	Type	Required	Description
`generation_id`	UUID	Yes	Durable task identifier owned by the credential's account and App.
`status`	string	Yes	Poll until succeeded, failed or cancelled; an accepted request is not completion.
`model_key / modality / operation`	string	Yes	Selected model, image/video modality and public operation.
`created_at / updated_at`	ISO UTC string	Yes	UTC timestamps.
`completed_at`	ISO UTC string	No	Completion time when present.
`poll_after_ms`	integer	No	Suggested delay for nonterminal tasks (currently 2000); omitted for terminal tasks.
`estimated_credits / reserved_credits / charged_credits`	integer	Yes	Estimated, reserved and actually charged account credits.
`outputs`	object[]	Yes	media_id, media_type, url, and optional width, height, duration_ms.
`error`	object	No	Task failure: code, message, retryable. Omitted when absent.
`client_trace_id`	string	No	Echoed client correlation identifier when provided.

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "generation_id": "11111111-1111-4111-8111-111111111111",
    "status": "queued",
    "model_key": "<model_key_from_catalog>",
    "modality": "image",
    "operation": "image_generation",
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:00.000Z",
    "poll_after_ms": 2000,
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": []
  }
}

Errors

401 — DEVELOPER_TOKEN_REQUIRED
401 — DEVELOPER_TOKEN_INVALID / DEVELOPER_TOKEN_EXPIRED / DEVELOPER_TOKEN_REVOKED
403 — DEVELOPER_SCOPE_INSUFFICIENT
404 — TASK_NOT_FOUND / GENERATION_JOB_NOT_FOUND

Missing bearer returns REQUIRED; invalid credentials, including historical anonymous tokens, return INVALID. Expired or revoked credentials use their corresponding codes.

{
  "success": false,
  "code": "DEVELOPER_TOKEN_REQUIRED",
  "message": "A developer bearer token is required.",
  "request_id": "docs-example"
}