---
title: "Long-poll a job to completion"
method: GET
path: "/v1/jobs/{id}"
tags: ["Jobs"]
---

# Long-poll a job to completion

`GET /v1/jobs/{id}`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/jobs/{id}`
- Auth: HTTP bearer

Returns job status and output URLs. Pass `?wait=true` to long-poll until the job completes or fails (up to ~60s). Returns 404 if the job does not exist or is not owned by the caller.

Select Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `wait` 'true' | 'false': If true, long-poll until the job completes, fails, or timeout is reached. If false or omitted, return the current status immediately.
- `timeout` number: Long-poll timeout in seconds when wait=true. 1 to 120. Defaults to 120. On timeout the response is 200 with the current (still pending) job state, not 408.
- `api_version` '2026-09-26' | 'legacy'

## Headers

- `Masko-API-Version` '2026-09-26' | 'legacy'

## Response `200`

Job details

- union
  - StudioJobResponse
    - `data` StudioJob, required
      - `object` 'job': Resource type. Always "job".
      - `variant_id` string, uuid, nullable, required: Selected mascot variant, or null for original-context and older untagged jobs.
      - `generation_context` object: Frozen generation context: variant id and name, engine hash, the mascot prompt and style you provided, reference asset IDs and asset inputs. Transitions include transition.before and transition.after with pose IDs and saved variant contexts; video edits add transition_edit with the source video and requested edit. Internal generation execution details are never included.
      - `id` string, uuid, required
      - `status` 'pending' | 'processing' | 'completed' | 'failed', required
      - `type` 'item_generation' | 'image_generation' | 'logo' | 'animation' | 'video_edit' | 'reverse' | 'size_variant' | 'size_variant_batch' | 'export_animation' | 'scene_generation' | 'sticker_generation' | 'svg_generation' | 'interactive_generation' | 're_export' | 'canvas_orchestration' | 'mascot_brand_book', required
      - `mascot_id` string, uuid, nullable, required
      - `cost_credits` number, required
      - `created_at` string, required
      - `updated_at` string, required
      - `item_id` string, uuid, nullable
      - `item_name` string, nullable
      - `error` string, nullable
      - `urls` object
      - `step` 'pages' | 'read' | 'generate' | 'mascot' | 'failed' | 'null', nullable: mascot_brand_book jobs: pages (turning files into pages), read (free reading), generate (paid images), mascot (filling its context).
      - `result` object: Completed mascot_brand_book jobs: the mascot created.
        - `mascot_id` string, uuid, required
        - `mascot_name` string, required
        - `references` integer, required: Generated views saved as labeled references.
        - `props` integer, required: Generated props saved.
        - `credits_charged` integer, required: After refunds for images that failed.
  - JobResponse
    - `data` Job, required
      - `object` 'job': Resource type. Always "job".
      - `variant_id` string, uuid, nullable, required: Selected mascot variant, or null for original-context and older untagged jobs.
      - `generation_context` object: Frozen generation context: variant id and name, engine hash, the mascot prompt and style you provided, reference asset IDs and asset inputs. Transitions include transition.before and transition.after with pose IDs and saved variant contexts; video edits add transition_edit with the source video and requested edit. Internal generation execution details are never included.
      - `id` string, uuid, required
      - `status` 'pending' | 'processing' | 'completed' | 'failed', required
      - `type` 'item_generation' | 'image_generation' | 'logo' | 'animation' | 'video_edit' | 'reverse' | 'size_variant' | 'size_variant_batch' | 'export_animation' | 'scene_generation' | 'sticker_generation' | 'svg_generation' | 'interactive_generation' | 're_export' | 'canvas_orchestration' | 'mascot_brand_book', required
      - `collection_id` string, uuid, nullable, required
      - `cost_credits` number, required
      - `created_at` string, required
      - `updated_at` string, required
      - `item_id` string, uuid, nullable
      - `item_name` string, nullable
      - `error` string, nullable
      - `urls` object
      - `step` 'pages' | 'read' | 'generate' | 'mascot' | 'failed' | 'null', nullable: mascot_brand_book jobs: pages (turning files into pages), read (free reading), generate (paid images), mascot (filling its context).
      - `result` object: Completed mascot_brand_book jobs: the mascot created.
        - `mascot_id` string, uuid, required
        - `mascot_name` string, required
        - `references` integer, required: Generated views saved as labeled references.
        - `props` integer, required: Generated props saved.
        - `credits_charged` integer, required: After refunds for images that failed.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict

---

[API](https://skmtc.dev/masko/apis/masko-api.md) · [All operations](https://skmtc.dev/masko/apis/masko-api/llms.txt) · [OpenAPI document](https://skmtc.dev/masko/apis/masko-api/revisions/91eb3006a92f?raw)