---
title: "Retrieve a list of jobs"
method: GET
path: "/api/v1/jobs"
tags: ["Jobs"]
---

# Retrieve a list of jobs

`GET /api/v1/jobs`

## Request

- Base URL: `https://api.sudomock.com`
- URL: `https://api.sudomock.com/api/v1/jobs`
- Auth: API key in header `x-api-key`

List the caller's async jobs (render, video, upload, or photo mockup creation), newest first and paginated by cursor. Optionally filter by kind and/or mockup_uuid (e.g. one mockup's videos). Each item has the SAME shape as GET /api/v1/jobs/{job_id} plus list display fields (duration_seconds/audio/mockup_name/poster_url).

## Query parameters

- `kind` string: Filter by job kind: video | render | upload | 2d_create | 2d_render | photo_mockup_create | photo_mockup_render. A photo-mockup kind selects both spellings of that job, and the listed jobs are spelled the way you asked. Omit for all kinds, each spelled as it was submitted.
- `mockup_uuid` string: Filter by source mockup UUID (e.g. a mockup's videos). Omit for all mockups. Raw-image videos (no source mockup) are never returned by this filter.
- `limit` integer: Max jobs per page (1-50).
- `cursor` string: Opaque cursor from a prior page's next_cursor.

## Response `200`

Successful Response

- JobListResponse: A page of your jobs, newest first.
  - `jobs` JobListItem[], required: The jobs on this page, newest first.
    - `job_id` string, required: Identifier of this job.
    - `kind` string, required: What this job does: render, video, upload, 2d_create, 2d_render, photo_mockup_create or photo_mockup_render.
    - `status` 'queued' | 'dispatched' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: Where the job stands, and it is over once this reads succeeded, failed or cancelled.
    - `result_url` string, nullable: Link to the finished file, or the path of the mockup that was created, and null until the job succeeds.
    - `mockup_uuid` string, nullable: Identifier of the mockup this job created, and null for jobs that hand back a file instead.
    - `error` JobError: Why a job produced no result.
      - `error_code` string, required: Stable code for this failure, safe to branch on in your own code.
      - `message` string, required: Plain language explanation of what went wrong.
    - `credits_charged` integer, nullable: Credits you actually paid for this job, which is zero once a failed or cancelled job has been refunded.
    - `payg` JobPaygCost: What this job costs at the account's pay as you go rate.
      - `credits` integer, nullable: Credits this job bills.
      - `unit_price` number, nullable: Price of one credit in US dollars for this account.
      - `cost` number, nullable: Total US dollars for this job, the credits multiplied by the unit price.
    - `watermark` JobWatermark: Why the result carries a watermark, and where to get results without one.
      - `reason` string, required: Why this result was marked.
      - `remove_url` string, required: Where to go to start getting unmarked results.
    - `created_at` string, required: When this job was submitted.
    - `updated_at` string, required: When this job last changed.
    - `model` string, nullable: The video model that produced this clip, present on video jobs only.
    - `outcome_tier` string, nullable: The quality level this clip was produced at, present on video jobs only.
    - `duration_seconds` integer, nullable: Length of the clip in seconds, and null for a job that is not a video.
    - `audio` boolean, nullable: Whether the clip was produced with sound, and null for a job that is not a video.
    - `mockup_name` string, nullable: Name of the mockup this job started from, and null when it started from an image instead.
    - `poster_url` string, nullable: Link to a still frame you can show before the clip plays, and null until that frame exists.
  - `next_cursor` string, nullable: Send this back as cursor to read the next page, and null when this is the last page.

---

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