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

# List Jobs

`GET /v1/jobs`

## Request

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

Your jobs, most recent first.

Served from the durable record, so history outlives the live job state.

## Query parameters

- `limit` integer
- `before` string, nullable: Return jobs older than this job id.
- `status` 'queued' | 'running' | 'succeeded' | 'failed'

## Response `200`

Successful Response

- JobList
  - `data` JobResponse[], required: This page of jobs, newest first.
    - `id` string, required
    - `custom_id` string, nullable: Your own identifier for the job, if you sent one.
    - `model` string, nullable: The model this job was sent to.
    - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
    - `flagged` boolean, nullable: Whether an automated check thought this job's images may fall outside what the service allows: the part of your image the job worked on (all of it, unless you named a region), and for some jobs the one that came back. `null` means they were not all checked.
    - `error` string, nullable: Why a failed job failed, in words meant for a person.
    - `error_code` string, nullable: The same fact as `error`, as a stable identifier to branch on. New codes appear as new things become worth telling apart, so treat an unfamiliar one as a failure you have no special handling for rather than as an error in itself. A failed job is never charged, whatever the code; `inference_failed` is the one worth singling out, because it means the fault was ours and the same request is worth retrying.
    - `community` boolean: Whether the job runs on the community queue, which runs on shared, free capacity and can wait longer at busy times. Explains a long wait that is not a fault.
    - `credits` integer, nullable: What this job was billed. A job is charged when it succeeds — a still at the model's image price, a video by its length — so this reads 0 until then, and stays 0 for a job that fails.
    - `created_at` string, date-time, nullable: When the job was submitted. ISO-8601, UTC.
    - `finished_at` string, date-time, nullable: When the job settled. ISO-8601, UTC. Not stated while a job is still queued or running.
    - `result` JobResult: A job's whole answer: the model's own fields, and the files it produced. A model that answers only in fields carries no `output`; one that produces only a file carries `output` and nothing else; one doing both needs nothing new. The model's fields are its own, and the model's `result_schema` in the catalog describes them.
      - `output` JobOutput: Where a finished job's file is, and what it is.
        - `url` string, required: A temporary link that serves the file inline, for showing a result in a page. Expires; fetch the file rather than keeping the link.
        - `download_url` string, required: The same file, served as a download so a browser saves it under a filename. A separate link because the disposition is signed in; neither can be turned into the other.
        - `content_type` string, nullable: The file's media type.
        - `bytes` integer, nullable: The file's size, in bytes.
      - `input` JobFile: A file a job produced, other than the principal output.
        - `url` string, required: A temporary link that serves the file inline. Expires; fetch the file rather than keeping the link.
        - `content_type` string, nullable: The file's media type.
        - `bytes` integer, nullable: The file's size, in bytes.
    - `thumbnail_url` string, nullable: A temporary link to a small preview of the job's picture — the result, or the image the model worked from when the job produced no file — for showing a list of jobs without fetching each one whole. Absent until the job succeeds, where no preview could be made, and once the job's pictures are deleted.
    - `kept` boolean: Whether this result was asked to outlive the ordinary retention schedule.
    - `gallery` GalleryState: A job's live gallery submission, as a read of the job reports it.
      - `status` 'pending' | 'approved', required: `pending` while the submission is being reviewed, `approved` once it is on the gallery.
      - `post_id` string, required: The submission's id — what `DELETE /v1/gallery/{post_id}` withdraws.
    - `progress` JobProgress: How far a running job has got.
      - `stage` 'starting' | 'processing' | 'saving', required: `starting` while your file is fetched and read, `processing` while the model runs, `saving` while the result is stored.
      - `fraction` number, nullable: Roughly how much of the run is done, from 0 up to but never reaching 1, estimated from how long recent jobs like this one have taken. Null when no estimate holds: none is available yet, or the job has run past it.
    - `eta_seconds` number, nullable: Rough seconds until the job finishes — the wait for capacity plus the time running. Not stated once a job has settled, so a callback never carries one.
  - `has_more` boolean, required: Whether more jobs remain past this page.
  - `next_before` string, nullable: Pass as `before` to fetch the next page. Absent on the last one.

## Other responses

- `400`: the path, query or a JSON string in the body contains a NUL character or an unpaired surrogate; the body is not JSON encoded as UTF-8, or carries a number JSON cannot represent (NaN, Infinity, or one too large) or nesting too deep to read; or an Idempotency-Key header is longer than 255 characters or not printable ASCII. The request was not read
- `401`: missing, malformed or unrecognised API key
- `413`: the request body is larger than 1 MiB. The request was not read
- `422`: Validation Error

---

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