---
title: "List generation jobs"
method: GET
path: "/v1/jobs"
tags: ["Jobs"]
---

# List generation jobs

`GET /v1/jobs`

## Request

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

Returns paginated generation jobs owned by the caller, newest first. Use to track recent activity or find a specific job. Filter by status or mascot. No credit cost.

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.

## Query parameters

- `limit` number: Page size. 1 to 100. Defaults to 50.
- `offset` number, nullable: Number of records to skip. Defaults to 0.
- `cursor` string: Opaque next_cursor from the previous page. Use instead of offset.
- `from_variant_id` string, uuid: Filter transitions by the variant of the starting pose.
- `to_variant_id` string, uuid: Filter transitions by the variant of the ending pose.
- `variant_id` string, uuid: Filter jobs by their single variant. Cross-variant transitions have no single variant; use from_variant_id or to_variant_id.
- `status` string: Filter by status: pending, processing, completed, failed.
- `mascot_id` string, uuid: Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404.
- `type` string: Filter by job type. Values: item_generation, image_generation, logo, animation, video_edit, reverse, size_variant, size_variant_batch, export_animation, scene_generation, interactive_generation, sticker_generation, svg_generation.
- `api_version` '2026-09-26' | 'legacy'
- `collection_id` string, uuid: Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404.

## Headers

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

## Response `200`

List of jobs

- union
  - StudioJobListResponse
    - `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.
    - `meta` Meta, required
      - `pagination` Pagination
        - `total` integer, required
        - `limit` integer, required
        - `offset` integer, required
        - `has_more` boolean, required
        - `next_cursor` string, nullable: Pass as the cursor query parameter to get the next page. Null on the last page.
  - JobListResponse
    - `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.
    - `meta` Meta, required
      - `pagination` Pagination
        - `total` integer, required
        - `limit` integer, required
        - `offset` integer, required
        - `has_more` boolean, required
        - `next_cursor` string, nullable: Pass as the cursor query parameter to get the next page. Null on the last page.

## 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)