Skip to content

List jobs by status and type

GET
/admin/jobs

Returns stored background jobs, optionally filtered by status and type.

You need to be signed in with system.jobs.read or system.admin for the whole install; a permission held only for a team doesn’t count.

Filters match exact, case-sensitive values; leave one out to include every value. An unknown status or type normally matches no rows. Results cover every stored state, sorted by priority ascending and then enqueued_at, and equal sort keys have no further order. This order isn’t a promise about when jobs start or finish: schedules, available workers, type limits and row locks also affect which job is claimed.

Page with limit and offset; the default page size is 50 and the maximum is 200. The page and total are separate database reads, so concurrent changes can make them disagree or move jobs between pages. With no matches, items is empty and total is zero; an offset past the end can return an empty page with a positive total.

attempts counts claims, not successful completions. A non-terminal failure normally puts a job back to pending while attempts remain, and a terminal failure can produce failed before the limit is reached. running records a claim, not proof that its worker is alive. The watchdog returns a job with an expired lease to pending even when the attempt limit has already been reached, and that row can’t be claimed again without further intervention. done means the handler reported success, which can include work it skipped.

The list leaves out payloads and results but includes stored error text and claim details. It reads the database directly, with no jobs-list cache. Completed rows become eligible for the default hourly cleanup after seven days; that cleanup doesn’t remove failed or cancelled rows.

status
string

Exact job status to match: pending, running, done, failed or cancelled. Omit to include every status.

type
string

Exact job type to match, such as preview.raster. Omit to include every type.

limit
integer
default: 50 >= 1 <= 200

Maximum number of items to return, from 1 to 200; defaults to 50. After conversion to a 32-bit integer, values of 0 or less use 50 and values above 200 use 200.

offset
integer
0

Number of matching rows to skip. Use a non-negative integer; the default is zero.

A page of stored job summaries and a separately read total for the same filters.

A page of stored background job summaries.

object
items
required

Jobs on this page, ordered by priority and then enqueue time. Empty when no rows match this page.

Array<object>

Stored state and timing information for a background job. Payload and result data are not included.

object
id
required

UUID of this job row. Administrative requeueing keeps it.

string format: uuid
type
required

Job type used for handler selection, such as preview.raster.

string
status
required

Stored queue state: pending, running, done, failed or cancelled. running is a recorded claim, not proof the worker is alive; failed can mean a terminal error or exhausted attempts.

string
Allowed values: pending running done failed cancelled
priority
required

Queue priority; lower numbers are considered first among eligible, unlocked jobs. Equal priorities are ordered by enqueue time.

integer
attempts
required

Number of claims since creation or the most recent administrative requeue, which resets this count to zero.

integer
max_attempts
required

Claim limit used by workers. A pending row at or above this value is not eligible for another claim.

integer
claimed_by

Recorded worker ID. Completed jobs can keep it, so its presence alone doesn’t mean work is running. Left out when absent.

string
nullable
claimed_at

When the claim was recorded. Completed jobs can keep it. Left out when absent.

string format: date-time
nullable
lease_expires_at

Recorded lease expiry. The watchdog can requeue a job whose lease has expired, but expiry doesn’t prove the handler has stopped. Left out when absent.

string format: date-time
nullable
last_error

Stored error text from job processing or lease recovery, cleared on completion or administrative requeue. Left out when absent.

string
nullable
origin_server_id

Stored origin-server UUID, if any. Left out otherwise.

string format: uuid
nullable
scheduled_for

Earliest claim time, set by the code that queued the job. Administrative requeueing keeps it. Left out for unscheduled work.

string format: date-time
nullable
enqueued_at

Original enqueue time, preserved across automatic and administrative retries.

string format: date-time
nullable
started_at

First recorded claim time, kept across retries and administrative requeueing. Left out before the first claim.

string format: date-time
nullable
finished_at

When the job completed, failed terminally or was cancelled. Administrative requeueing clears it. Left out when absent.

string format: date-time
nullable
age_seconds
required

Seconds since the original enqueue time, calculated by the database and rounded to an integer. This is not handler execution time.

integer format: int64
total
required

Matching stored rows across all pages. It’s read separately from items, so concurrent changes can make the two disagree.

integer format: int64

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"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed