Skip to content

List future scheduled jobs

GET
/admin/jobs/scheduled

Returns pending jobs scheduled for a future time.

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.

Only rows with status pending and a non-null scheduled_for strictly later than the database query time are included. Results are sorted by scheduled_for, soonest first, and equal times have no further order. Due, unscheduled and non-pending jobs are left out. A listed row can still be unclaimable because it has reached its attempt limit.

Page with limit and offset; the default is 50 and the maximum is 200. The page and total are separate reads, and time passing, claims and concurrent writes can make them disagree or move rows 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.

The database calculates due_in_seconds and rounds it to an integer, so a future job can show zero just before it’s due. A schedule sets the earliest time a worker may claim the job, not a promised start time. This endpoint lists queued rows; it doesn’t define recurring schedules or offer a scheduling editor.

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 future pending jobs and a separately read total.

A page of pending jobs whose schedule is still in the future.

object
items
required

Future pending jobs on this page, ordered by scheduled time. Empty when no rows match the page.

Array<object>

A pending job with a scheduled time later than the database query time.

object
id
required

UUID of the job row.

string format: uuid
type
required

Stored job type.

string
status
required

Stored status; this endpoint selects pending rows only.

string
priority
required

Stored queue priority. Once the schedule is due, lower values are considered first among eligible, unlocked jobs.

integer
attempts
required

Claims recorded since creation or administrative requeue. A future schedule doesn’t mean another attempt remains.

integer
max_attempts
required

Maximum claim count used by workers.

integer
scheduled_for

Earliest time the job may be claimed, not a guaranteed start time. Always present on rows this endpoint returns.

string format: date-time
nullable
enqueued_at

Original enqueue time, preserved across retries.

string format: date-time
nullable
due_in_seconds
required

Seconds until scheduled_for, calculated by the database and rounded to an integer. It can be zero for a job due in under half a second.

integer format: int64
total
required

Future pending rows across all pages, counted in a separate query. Time passing or concurrent changes can make it disagree with items.

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