---
title: "Get Job"
method: GET
path: "/v1/jobs/{job_id}"
tags: ["jobs"]
---

# Get Job

`GET /v1/jobs/{job_id}`

## Request

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

The whole job in one read: status, the charge and the result.

A job belonging to another account answers 404 rather than 403. Confirming that someone
else's job exists would itself be a disclosure, so the two cases are deliberately
indistinguishable from outside.

## Path parameters

- `job_id` string, required

## Response `200`

Successful Response

- JobResponse: A job as the API states it. An absent field means it does not apply to this job — a queued one has no result, a finished one has no estimate — rather than that it is unknown.
  - `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.

## 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
- `404`: unknown job, or not yours
- `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)