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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Exact job status to match: pending, running, done, failed or cancelled. Omit to include every status.
Exact job type to match, such as preview.raster. Omit to include every type.
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.
Number of matching rows to skip. Use a non-negative integer; the default is zero.
Responses
Section titled “ Responses ”A page of stored job summaries and a separately read total for the same filters.
A page of stored background job summaries.
object
Jobs on this page, ordered by priority and then enqueue time. Empty when no rows match this page.
Stored state and timing information for a background job. Payload and result data are not included.
object
UUID of this job row. Administrative requeueing keeps it.
Job type used for handler selection, such as preview.raster.
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.
Queue priority; lower numbers are considered first among eligible, unlocked jobs. Equal priorities are ordered by enqueue time.
Number of claims since creation or the most recent administrative requeue, which resets this count to zero.
Claim limit used by workers. A pending row at or above this value is not eligible for another claim.
Recorded worker ID. Completed jobs can keep it, so its presence alone doesn’t mean work is running. Left out when absent.
When the claim was recorded. Completed jobs can keep it. Left out when absent.
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.
Stored error text from job processing or lease recovery, cleared on completion or administrative requeue. Left out when absent.
Stored origin-server UUID, if any. Left out otherwise.
Earliest claim time, set by the code that queued the job. Administrative requeueing keeps it. Left out for unscheduled work.
Original enqueue time, preserved across automatic and administrative retries.
First recorded claim time, kept across retries and administrative requeueing. Left out before the first claim.
When the job completed, failed terminally or was cancelled. Administrative requeueing clears it. Left out when absent.
Seconds since the original enqueue time, calculated by the database and rounded to an integer. This is not handler execution time.
Matching stored rows across all pages. It’s read separately from items, so concurrent changes can make the two disagree.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed