Modifying Job Data

Note

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

Zizq is designed with visibility and control front of mind. A number of endpoints exist that allow updating and deleting job data from the server.

Jobs in the "completed" and "dead" statuses are immutable and cannot be modified, though they can be deleted.

The following fields are mutable:

queue
priority
ready_at
retry_limit
backoff
retention

`DELETE /jobs/{id}`

Delete a single job given a known ID.

Parameters

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

Responses

`404` Not Found

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

`DELETE /jobs`

Delete jobs matching the given filters. When no filters are specified, all jobs are deleted.

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 delete.
`queue` query string	Optional comma-separated list of queue names to filter by.
`type` query string	Optional comma-separated list of job types to filter by.
`status` query string	Optional comma-separated list of job statuses to filter by.
`filter` query string	Optional `jq` expression to filter jobs by `payload`.

Responses

`200` OK

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

`400` Bad Request

When given invalid input parameters.

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

`PATCH /jobs/{id}`

Update a single job’s mutable fields. Only fields included in the request body are changed. Fields set to null are cleared to the server default. Fields omitted from the request are left unchanged.

Note

Jobs in a terminal state (completed or dead) cannot be patched. The server returns 422 Unprocessable Entity in this case.

Tip

Setting ready_at to a future timestamp on a "ready" job moves it to the scheduled status. Setting ready_at to null on a scheduled job makes it immediately ready.

Parameters

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

Request Body

All fields are optional. Only include the fields you wish to change.

Field	Description
`queue` string	Move the job to a different queue. Must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`. When the key is present, cannot be `null`.
`priority` int16	Change the job's priority. Lower numbers are higher priority. When the key is present, cannot be `null`.
`ready_at` int64 \| null	Change when the job becomes ready (milliseconds since epoch). Setting to `null` makes a scheduled job immediately ready.
`retry_limit` int32 \| null	Override the retry limit. Setting to `null` clears back to the server default.
`backoff` object \| null	Override the backoff configuration. Setting to `null` clears back to the server default. When provided, all three sub-fields (`exponent`, `base_ms`, `jitter_ms`) are required.
`retention` object \| null	Override the retention configuration. Setting to `null` clears back to the server default. When provided as an object, individual sub-fields are merge-patched — omitted sub-fields are left unchanged, sub-fields set to `null` are cleared.

Responses

`200` OK

Returns the updated job without the payload.

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`.
`duplicate` required boolean	Only returned on enqueue responses. Set to `true` if this job was a duplicate enqueue of an existing job according to its `unique_key` and `unique_while` scope.
`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.

`404` Not Found

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

`422` Unprocessable Entity

When the job is in a terminal state or invalid values are provided.

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

Update all jobs matching the given filters. The request body specifies the fields to change (same as PATCH /jobs/{id}). The query parameters specify which jobs to update (same filters as DELETE /jobs).

Jobs in a terminal state ("completed" or "dead") are silently skipped unless explicitly requested via ?status=, in which case the server returns 422 Unprocessable Entity.

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 filter options are additive.

Field	Description
`id` query string	Optional comma-separated list of job IDs to update.
`queue` query string	Optional comma-separated list of queue names to filter by.
`type` query string	Optional comma-separated list of job types to filter by.
`status` query string	Optional comma-separated list of job statuses to filter by. Must not include `completed` or `dead`.
`filter` query string	Optional `jq` expression to filter jobs by `payload`.

Field	Description
`patched` required int64	The number of jobs that were updated.

`400` Bad Request

When given invalid input parameters.

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

`422` Unprocessable Entity

When the status filter includes terminal statuses, or invalid field values are provided.

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

Examples

Update a job’s queue and priority

http PATCH 127.0.0.1:7890/jobs/03fvmbsuryhdkxvb6vjy4qhxp <<'JSON'
{"queue": "other", "priority": 100}
JSON

HTTP/1.1 200 OK
content-length: 141
content-type: application/json
date: Fri, 03 Apr 2026 11:10:58 GMT

{
    "attempts": 0,
    "id": "03fvmbsuryhdkxvb6vjy4qhxp",
    "priority": 100,
    "queue": "other",
    "ready_at": 1775214099613,
    "status": "ready",
    "type": "hello_world"
}

Move a job from `ready` to `scheduled`

http PATCH 127.0.0.1:7890/jobs/03fvmbsuryhdkxvb6vjy4qhxp <<'JSON'
{"ready_at": 1775217412000}
JSON

HTTP/1.1 200 OK
content-length: 145
content-type: application/json
date: Fri, 03 Apr 2026 11:13:10 GMT

{
    "attempts": 0,
    "id": "03fvmbsuryhdkxvb6vjy4qhxp",
    "priority": 100,
    "queue": "other",
    "ready_at": 1775217412000,
    "status": "scheduled",
    "type": "hello_world"
}

Clear a field back to server default

Setting an optional field to null resets it to the server’s default value.

http PATCH 127.0.0.1:7890/jobs/03fvmbsuryhdkxvb6vjy4qhxp <<'JSON'
{"retry_limit": null}
JSON

HTTP/1.1 200 OK
content-length: 145
content-type: application/json
date: Fri, 03 Apr 2026 11:15:20 GMT

{
    "attempts": 0,
    "id": "03fvmbsuryhdkxvb6vjy4qhxp",
    "priority": 100,
    "queue": "other",
    "ready_at": 1775217412000,
    "status": "scheduled",
    "type": "hello_world"
}

Move all jobs from one queue to another

http PATCH http://127.0.0.1:7890/jobs?queue=example <<'JSON'
{"queue": "other"}
JSON

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

{
    "patched": 4
}

Remove all scheduled jobs on a queue

http DELETE "http://127.0.0.1:7890/jobs?queue=example&status=scheduled"

HTTP/1.1 200 OK
content-length: 13
content-type: application/json
date: Fri, 03 Apr 2026 11:18:36 GMT

{
    "deleted": 2
}

Safely delete jobs matching filters in pages

To delete jobs matching a filter in a paginated way, a two step approach is used:

Query the jobs using the desired filters.
Delete the jobs using filters and the IDs on each page.

It’s important to retain the filters to handle race conditions if the jobs are modified between fetching the page and executing the delete.

http GET 'http://127.0.0.1:7890/jobs?filter=.greet | startswith("Wo")&limit=2'

HTTP/1.1 200 OK
content-length: 624
content-type: application/json
date: Fri, 03 Apr 2026 11:22:34 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&filter=.greet%20%7C%20startswith%28%22Wo%22%29",
        "prev": null,
        "self": "/jobs?order=asc&limit=2&filter=.greet%20%7C%20startswith%28%22Wo%22%29"
    }
}

http DELETE 'http://127.0.0.1:7890/jobs?filter=.greet | startswith("Wo")&id=03fvmaj8q5po1huy5nd4xmi5f,03fvmame0wyuiexbc2033jby2'

HTTP/1.1 200 OK
content-length: 13
content-type: application/json
date: Fri, 03 Apr 2026 11:23:52 GMT

{
    "deleted": 2
}

Zizq API Reference

Modifying Job Data

`DELETE /jobs/{id}`

Parameters

Responses

`204` No Content

`404` Not Found

`DELETE /jobs`

Parameters

Responses

`200` OK

`400` Bad Request

`PATCH /jobs/{id}`

Parameters

Request Body

Responses

`200` OK

`404` Not Found

`422` Unprocessable Entity

`PATCH /jobs`

Parameters

Request Body

Responses

`200` OK

`400` Bad Request

`422` Unprocessable Entity

Examples

Update a job’s queue and priority

Move a job from `ready` to `scheduled`

Clear a field back to server default

Move all jobs from one queue to another

Remove all scheduled jobs on a queue

Safely delete jobs matching filters in pages

Keyboard shortcuts

Zizq API Reference