Querying Job Data

Note

These endpoints are available in both application/json and application/msgpack formats.

Zizq is designed with visibility front of mind. A number of endpoints exist that allow retrieving job data from the server without actually dequeueing the jobs.

Common Job Type

All endpoints return the same Job structure.

Field	Description
`id` required string	Unique time-sequenced job ID assigned by the server.
`queue` required string	Arbitrary queue name to which the job is assigned
`type` required string	Job type known to your application
`priority` required int16	Numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`status` required string	The job status on the server. One of: `scheduled` `ready` `in_flight` `completed` `dead` Actual statuses shown will be context-dependent.
`unique_key` string	Optional unique key for this job, which is used to protect against duplicate job enqueues. This is paired with the optional `unique_while` field which defines the scope within which the job is considered unique.
`unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Conflicting jobs will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Conflicting jobs will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Conflicting jobs will not be enqueued while this job exists in any status (i.e. until the job is reaped, according to the retention policy). The default scope is `queued`.
`payload` required object	Any JSON-serializable type to be processed by your application.
`batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`budgets[].key` required* string	The identifier for the budget.
`budgets[].cost` required* int32	The number of tokens this job takes from the budget.
`ready_at` required int64	The timestamp at which this job is ready to be dequeued by workers.
`attempts` required int32	The number of times this job has been previously attempted (starts at zero).
`backoff` object	Optional backoff policy which overrides the server's default policy. All fields are required. Zizq computes the backoff delay as `base_ms + (attempts^exponent) + (rand(0.0..jitter_ms)*attempts)`. The `jitter_ms` mitigates retry flooding when failures occur clustered together.
`backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`backoff.exponent` float	A multiplier applied to the number of attempts on each retry, used as `pow(attempts, exponent)` to produce an increasing delay in milliseconds.
`backoff.jitter_ms` int32	A random delay added onto each attempt. Multiplied by the total number of attempts, such as `attempts * rand(0..jitter)`. Prevents retries clutering together.
`retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`retention.dead_ms` int64	The number of milliseconds for which to retain `dead` jobs after all retries have been exhausted. When not set, the server's default value (7 days) applies. When set to zero, jobs are purged as soon as all retries have been exhausted.
`retention.completed_ms` int64	The number of milliseconds for which to retain `completed` jobs after successful processing. When not set, the server's default value (zero) applies. When set to zero, jobs are purged immediately upon completion.
`budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`budgets[].key` required* string	The identifier for the budget.
`budgets[].cost` int32 required*	The number of tokens this job takes from the budget.

`GET /queues`

Get the list of all queues known to the server.

Note

Queues are not explicitly created in Zizq. Jobs are assigned to arbitrary queue names.

Responses

`200` OK

Field	Description
`queues` required array	Array of queue names (strings).

`GET /jobs`

Retrieve a filtered, paginated list of all jobs. Jobs are returned in FIFO order by default (i.e. ordered by the job ID, not necessarily prioritised).

Note

Zizq uses cursor-based pagination. Pages are enumerated by following the links in the response data

Tip

For more details on the query language used in the ?filter= parameter, read the language specification on the jaq website or on jq.

Tip

The priority, ready_at, and attempts parameters accept a range expression with inclusive bounds on both ends. Four shapes are supported:

Shape Meaning

N Exactly N (sugar for N..N).

A..B Between A and B.

..B At most B.

A.. At least A.

Requests where the lower bound exceeds the upper bound are rejected with 400 Bad Request.

Shape	Meaning
`N`	Exactly `N` (sugar for `N..N`).
`A..B`	Between `A` and `B`.
`..B`	At most `B`.
`A..`	At least `A`.

Parameters

All options are additive.

Field	Description
`id` query string	Optional comma-separated list of job IDs to include.
`queue` query string	Optional comma-separated list of queue names to include. Defaults to all queues.
`type` query string	Optional comma-separated list of job types to include. Defaults to all types.
`status` query string	Optional comma-separated list of job statuses to include. Defaults to all statuses.
`priority` query range	Optional inclusive range filter on the job's priority. Lower numbers are higher priority.
`ready_at` query range	Optional inclusive range filter on the job's `ready_at` timestamp (milliseconds since the Unix epoch).
`attempts` query range	Optional inclusive range filter on the job's failure count. For example `0` selects jobs that have never failed, `1..` selects anything that has failed at least once.
`budgets.key` query string	Optional comma-separated list of budget keys to which jobs are bound. Jobs matching any of the keys are included.
`filter` query string	Optional `jq` expression by which to filter jobs by `payload`. This enables matching on the entire payload, or arbitrarily on a subset of the payload. Filtering is done via jaq which is compatible with `jq`.
`order` query string	Whether to return the results ordered ascending or descending by ID. One of: `asc` `desc` The default order is `asc`.
`limit` query int16	The maximum number of jobs to include per page. Valid values are between 1 and 2000. The default is 50.

Responses

`200` OK

Field	Description
`jobs` required array	Array of jobs for a single page using the common Job type.
`pages` required object	Links for the client to navigate to previous and next pages in the result. Each link is an absolute path that must be appended to the base URL.
`pages.self` required string	Link to be used to retrieve the current page of jobs.
`pages.next` string	Link to be used to retrieve the next page of jobs if more pages exist.
`pages.prev` string	Link to be used to retrieve the previous page of jobs if previous pages exist.

`400` Bad Request

When given invalid input parameters.

Field	Description
`error` required string	A description of the error.

`GET /jobs/{id}`

Retrieve a single job given a known ID.

Parameters

Field	Description
`id` path string	ID of the job to retrieve.

Responses

`200` OK

See Common Job Type.

`404` Not Found

Field	Description
`error` required string	A description of the error.

`GET /jobs/count`

Get the total number of jobs matching the given parameters.

Tip

The priority, ready_at, and attempts parameters accept a range expression with inclusive bounds on both ends. Four shapes are supported:

Shape Meaning

N Exactly N (sugar for N..N).

A..B Between A and B.

..B At most B.

A.. At least A.

Requests where the lower bound exceeds the upper bound are rejected with 400 Bad Request.

Shape	Meaning
`N`	Exactly `N` (sugar for `N..N`).
`A..B`	Between `A` and `B`.
`..B`	At most `B`.
`A..`	At least `A`.

Parameters

All options are additive.

Field	Description
`id` query string	Optional comma-separated list of job IDs to include.
`queue` query string	Optional comma-separated list of queue names to include. Defaults to all queues.
`type` query string	Optional comma-separated list of job types to include. Defaults to all types.
`status` query string	Optional comma-separated list of job statuses to include. Defaults to all statuses.
`priority` query range	Optional inclusive range filter on the job's priority. Lower numbers are higher priority.
`ready_at` query range	Optional inclusive range filter on the job's `ready_at` timestamp (milliseconds since the Unix epoch).
`attempts` query range	Optional inclusive range filter on the job's failure count. For example `0` selects jobs that have never failed, `1..` selects anything that has failed at least once.
`budgets.key` query string	Optional comma-separated list of budget keys to which jobs are bound. Jobs matching any of the keys are included.
`filter` query string	Optional `jq` expression by which to filter jobs by `payload`. This enables matching on the entire payload, or arbitrarily on a subset of the payload. Filtering is done via jaq which is compatible with `jq`.

Responses

`200` OK

Field	Description
`count` required int64	The number of jobs that were matched.

`400` Bad Request

When given invalid input parameters.

Field	Description
`error` required string	A description of the error.

`GET /jobs/{id}/errors`

Retrieve a paginated list of errors for a known job in order of attempt.

Note

Zizq uses cursor-based pagination. Pages are enumerated by following the links in the response data

Parameters

Field	Description
`id` path string	ID of the job for which to retrieve errors.

Responses

`200` OK

Field	Description
`errors` required array	Array of error objects for this page.
`errors[].attempt` required* int32	The attempt number of the job that failed.
`errors[].message` required* string	The error message sent by the client when the job failed.
`errors[*].error_type` string	The error type sent by the client when the job failed.
`errors[*].backtrace` string	The backtrace associated with the error, if specified by the client.
`errors[].dequeued_at` required* int64	The timestamp at which the failing job was dequeued by the worker.
`errors[].failed_at` required* int64	The timestamp at which the job failed.
`pages` required object	Links for the client to navigate to previous and next pages in the result. Each link is an absolute path that must be appended to the base URL.
`pages.self` required string	Link to be used to retrieve the current page of errors.
`pages.next` string	Link to be used to retrieve the next page of errors if more pages exist.
`pages.prev` string	Link to be used to retrieve the previous page of errors if previous pages exist.

`400` Bad Request

When given invalid input parameters.

Field	Description
`error` required string	A description of the error.

`404` Not Found

When the specified job does not exist.

Field	Description
`error` required string	A description of the error.

`GET /jobs/{id}/errors/{attempt}`

Retrieve a specific error for a known job and attempt.

Parameters

Field	Description
`id` path string	ID of the job for which to retrieve errors.
`attempt` path int32	The attempt number of the job that failed.

Responses

`200` OK

Field	Description
`attempt` required int32	The attempt number of the job that failed.
`message` required string	The error message sent by the client when the job failed.
`error_type` string	The error type sent by the client when the job failed.
`backtrace` string	The backtrace associated with the error, if specified by the client.
`dequeued_at` required int64	The timestamp at which the failing job was dequeued by the worker.
`failed_at` required int64	The timestamp at which the job failed.

`400` Bad Request

When given invalid input parameters.

Field	Description
`error` required string	A description of the error.

`404` Not Found

When the specified job or error does not exist.

Field	Description
`error` required string	A description of the error.

Examples

List all queues

Request:

http 127.0.0.1:7890/queues

Response:

HTTP/1.1 200 OK
content-length: 22
content-type: application/json
date: Fri, 03 Apr 2026 11:07:43 GMT

{
    "queues": [
        "comms",
        "default",
        "example",
        "payments"
    ]
}

List `ready` jobs on a specific queue

Request:

http GET "http://127.0.0.1:7890/jobs?queue=example&status=ready&limit=2"

Response:

HTTP/1.1 200 OK
content-length: 584
content-type: application/json
date: Fri, 03 Apr 2026 11:00:17 GMT

{
    "jobs": [
        {
            "attempts": 0,
            "id": "03fvmaj8q5po1huy5nd4xmi5f",
            "payload": {
                "greet": "World"
            },
            "priority": 500,
            "queue": "example",
            "ready_at": 1775213710452,
            "status": "ready",
            "type": "hello_world"
        },
        {
            "attempts": 0,
            "id": "03fvmame0wyuiexbc2033jby2",
            "payload": {
                "greet": "World"
            },
            "priority": 500,
            "queue": "example",
            "ready_at": 1775213737304,
            "status": "ready",
            "type": "hello_world",
            "unique_key": "hello_world:world",
            "unique_while": "queued"
        }
    ],
    "pages": {
        "next": "/jobs?from=03fvmame0wyuiexbc2033jby2&order=asc&limit=2&status=ready&queue=example",
        "prev": null,
        "self": "/jobs?order=asc&limit=2&status=ready&queue=example"
    }
}

Filter jobs by payload content

Note

The following example is intentionally not correctly percent-encoded for readability. HTTPie handles this ok.

Request:

http GET 'http://127.0.0.1:7890/jobs?filter=.greet | startswith("Uni")'

Response:

HTTP/1.1 200 OK
content-length: 301
content-type: application/json
date: Fri, 03 Apr 2026 11:02:51 GMT

{
    "jobs": [
        {
            "attempts": 0,
            "id": "03fvmbsuryhdkxvb6vjy4qhxp",
            "payload": {
                "greet": "Universe"
            },
            "priority": 500,
            "queue": "example",
            "ready_at": 1775214099613,
            "status": "ready",
            "type": "hello_world"
        }
    ],
    "pages": {
        "next": null,
        "prev": null,
        "self": "/jobs?order=asc&limit=50&filter=.greet%20%7C%20startswith%28%22Uni%22%29"
    }
}

Keyboard shortcuts

Zizq API Reference