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
`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.
`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.

`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.

Parameters

All options are additive.

Field	Description
`id` query string	Optional comma-separated list of job IDs to retrieve.
`queue` query string	Optional comma-separated list of queue names for which to list jobs. Defaults to all queues.
`type` query string	Optional comma-separated list of job types for which to list jobs. Defaults to all types.
`status` query string	Optional comma-separated list of job statuses for which to list jobs. Defaults to all statuses.
`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/{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

http 127.0.0.1:7890/queues

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

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

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.

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

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