Skip to content

Get a job

GET
/jobs/{id}

Returns a job’s full record: its payload, status, attempts, claim and lease, result and last error. Use it to follow a job you started or one you’re working on.

Any signed-in account can read any job by its id; nothing checks who queued it. The payload and result can hold the details of the request behind the job, such as a prompt or an asset id.

A cleanup that runs about every hour deletes jobs completed more than 7 days ago (by default), so a 404 can mean the job is gone as well as unknown.

id
required
string format: uuid

The job’s id.

The job.

object
id
required
string format: uuid
type
required
string
Example
preview.raster
payload

The job’s input, as queued. Its shape depends on type.

object
key
additional properties
any
status
required

Where the job is: pending (waiting to be claimed), running (claimed), done, failed, or cancelled by an administrator.

string
Allowed values: pending running done failed cancelled
priority
required

Lower numbers are claimed first; 100 is normal.

integer
attempts
required

How many times the job has been claimed since it was queued, or since an administrator last requeued it, which resets the count.

integer
max_attempts
required

The job isn’t offered again once attempts reaches this number, unless an administrator requeues it.

integer
claimed_by

The worker_id of the claim that holds the job, or that completed it. Left out while the job is waiting.

string
nullable
claimed_at

When that claim was made.

string format: date-time
nullable
lease_expires_at

When the lease runs out. A completed job keeps its last value, and a running job can show a time in the past until the server puts it back on the queue.

string format: date-time
nullable
last_error

The error from the last POST /jobs/{id}/fail, with [lease expired] added each time the server’s watchdog put the job back on the queue after its lease ran out. Cleared when the job completes.

string
nullable
result

What the worker sent when it completed the job. Left out until then, or if it sent nothing.

object
key
additional properties
any
origin_server_id
string format: uuid
nullable
scheduled_for

The earliest time the job can be claimed. It stays after that time has passed, and it’s left out when none was set. It isn’t a deadline.

string format: date-time
nullable
enqueued_at
required
string format: date-time
started_at

When the job was first claimed. Later attempts don’t change it.

string format: date-time
nullable
finished_at

When the job became done, failed or cancelled. A failure that puts the job back on the queue clears it.

string format: date-time
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed