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. Additionally, when modifying budget bindings jobs in the "in_flight" status cannot be updated (the operation can be retried once the job is no longer in-flight).

The following fields are mutable:

queue
priority
ready_at
retry_limit
backoff
retention
budgets

`DELETE /jobs/{id}`

Delete a single job given a known ID.

Parameters

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

Responses

`204` No Content

Job was successfully deleted.

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

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
`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
`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`.
`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.
`folded` required boolean	Only returned on enqueue responses. Set to `true` if this enqueue was folded into an existing pending batched job (see the `batch` object on the request and the Batched jobs section). Folded responses use HTTP `200 OK` rather than `201 Created`.
`batch` object	The batched-job configuration attached at enqueue time, if any. Echoed back on every job-fetch response so callers can observe the exact `when` / `fold` expressions the server is evaluating on subsequent folds (only the first enqueue's config applies for the life of the batch). See the enqueue-request table for the field shape.
`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.

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

`PATCH /jobs`

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.

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

Request Body

Same as PATCH /jobs/{id} Request Body.

Responses

`200` OK

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.

`POST /jobs/{id}/budgets/{key}`

Bind a single job to the named budget.

Parameters

Field	Description
`id` path string	ID of the job to which the budget will be bound.
`key` path string	The identifier for the budget. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.

Request Body

Field	Description
`cost` int32	The number of tokens the job takes from the budget. Defaults to 1.
`create_with` object	Specification from which to create this budget atomically with the binding if it does not already exist. Without this, the budget must exist or a 422 response will be returned. Does not overwrite any existing budget.
`create_with.allocation` required int32	The total number of tokens available in this budget's pool for use by its configured strategy. No jobs can exist bound to this budget with a `cost` that exceeds the allocation.
`create_with.strategy` required object	Details of the specific strategy that is used to manage the tokens available under this budget.
`create_with.strategy.type` required string	Names the strategy used to manage the tokens within the budget. One of: `while_in_flight` Concurrency control — tokens are spent from the budget when jobs are dispatched to workers, and returned when the job completes or fails, or the worker disconnects uncleanly. For example, for an allocation of 5, at most 5 jobs bound to this budget can be in-flight at any given time. `time_based` Rate limit — tokens are spent from the budget when jobs are dispatched to workers and are only returned after a configured period of time, regardless of the outcome of the job.
`create_with.strategy.duration_ms` int64	Required for `time_based` strategies. Invalid for `while_in_flight`. Specifies the period of time in milliseconds over which a `time_based` rate limit is measured. For example, for an allocation of 1000 and a `duration_ms` of 60000, the rate limit is `1000/minute`.
`create_with.strategy.burst` int32	The maximum number of tokens that may be accumulated at once for a `time_based` budget. Defaults to whatever the configured `allocation` is. So for a `1000/hour` rate limit, the budget would technically permit a short burst of 1000 jobs if no other jobs have used tokens from the budget for a whole hour. Setting a burst of 1 means tokens cannot accumulate and jobs are always paced according to the configured rate limit. It is also possible to intentionally set a burst higher than the configured allocation, such as a burst of 2000 for a `1000/hour` allocation. In this case if the budget has been idle for 2 hours, it would permit a sudden burst of 2000 jobs at any moment. No jobs can exist bound to this budget with a `cost` that exceeds the burst.

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
`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`.
`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.
`folded` required boolean	Only returned on enqueue responses. Set to `true` if this enqueue was folded into an existing pending batched job (see the `batch` object on the request and the Batched jobs section). Folded responses use HTTP `200 OK` rather than `201 Created`.
`batch` object	The batched-job configuration attached at enqueue time, if any. Echoed back on every job-fetch response so callers can observe the exact `when` / `fold` expressions the server is evaluating on subsequent folds (only the first enqueue's config applies for the life of the batch). See the enqueue-request table for the field shape.
`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.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`404` Not Found

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

`409` Conflict

When a budget with the named key is already bound to this job.

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

`422` Unprocessable Entity

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

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

`PUT /jobs/{id}/budgets/{key}`

Replace the named budget binding on a single job. Creates it if does not already exist.

Parameters

Field	Description
`id` path string	ID of the job to which the budget will be bound.
`key` path string	The identifier for the budget. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.

Request Body

Field	Description
`cost` int32	The number of tokens the job takes from the budget. Defaults to 1.
`create_with` object	Specification from which to create this budget atomically with the binding if it does not already exist. Without this, the budget must exist or a 422 response will be returned. Does not overwrite any existing budget.
`create_with.allocation` required int32	The total number of tokens available in this budget's pool for use by its configured strategy. No jobs can exist bound to this budget with a `cost` that exceeds the allocation.
`create_with.strategy` required object	Details of the specific strategy that is used to manage the tokens available under this budget.
`create_with.strategy.type` required string	Names the strategy used to manage the tokens within the budget. One of: `while_in_flight` Concurrency control — tokens are spent from the budget when jobs are dispatched to workers, and returned when the job completes or fails, or the worker disconnects uncleanly. For example, for an allocation of 5, at most 5 jobs bound to this budget can be in-flight at any given time. `time_based` Rate limit — tokens are spent from the budget when jobs are dispatched to workers and are only returned after a configured period of time, regardless of the outcome of the job.
`create_with.strategy.duration_ms` int64	Required for `time_based` strategies. Invalid for `while_in_flight`. Specifies the period of time in milliseconds over which a `time_based` rate limit is measured. For example, for an allocation of 1000 and a `duration_ms` of 60000, the rate limit is `1000/minute`.
`create_with.strategy.burst` int32	The maximum number of tokens that may be accumulated at once for a `time_based` budget. Defaults to whatever the configured `allocation` is. So for a `1000/hour` rate limit, the budget would technically permit a short burst of 1000 jobs if no other jobs have used tokens from the budget for a whole hour. Setting a burst of 1 means tokens cannot accumulate and jobs are always paced according to the configured rate limit. It is also possible to intentionally set a burst higher than the configured allocation, such as a burst of 2000 for a `1000/hour` allocation. In this case if the budget has been idle for 2 hours, it would permit a sudden burst of 2000 jobs at any moment. No jobs can exist bound to this budget with a `cost` that exceeds the burst.

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
`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`.
`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.
`folded` required boolean	Only returned on enqueue responses. Set to `true` if this enqueue was folded into an existing pending batched job (see the `batch` object on the request and the Batched jobs section). Folded responses use HTTP `200 OK` rather than `201 Created`.
`batch` object	The batched-job configuration attached at enqueue time, if any. Echoed back on every job-fetch response so callers can observe the exact `when` / `fold` expressions the server is evaluating on subsequent folds (only the first enqueue's config applies for the life of the batch). See the enqueue-request table for the field shape.
`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.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`404` Not Found

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

`409` Conflict

When a budget with the named key is already bound to this job.

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

`422` Unprocessable Entity

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

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

`PATCH /jobs/{id}/budgets/{key}`

Update the named budget binding on a single job. Currently the only patchable field is cost.

Parameters

Field	Description
`id` path string	ID of the job for which the budget is to be patched.
`key` path string	The identifier for the budget.

Request Body

Field	Description
`cost` required int32	The number of tokens the job takes from the budget.

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
`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`.
`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.
`folded` required boolean	Only returned on enqueue responses. Set to `true` if this enqueue was folded into an existing pending batched job (see the `batch` object on the request and the Batched jobs section). Folded responses use HTTP `200 OK` rather than `201 Created`.
`batch` object	The batched-job configuration attached at enqueue time, if any. Echoed back on every job-fetch response so callers can observe the exact `when` / `fold` expressions the server is evaluating on subsequent folds (only the first enqueue's config applies for the life of the batch). See the enqueue-request table for the field shape.
`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.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`404` Not Found

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

`422` Unprocessable Entity

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

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

`DELETE /jobs/{id}/budgets/{key}`

Remove the named budget binding from a single job.

Parameters

Field	Description
`id` path string	ID of the job for which the budget is to be removed.
`key` path string	The identifier for the budget.

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
`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`.
`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.
`folded` required boolean	Only returned on enqueue responses. Set to `true` if this enqueue was folded into an existing pending batched job (see the `batch` object on the request and the Batched jobs section). Folded responses use HTTP `200 OK` rather than `201 Created`.
`batch` object	The batched-job configuration attached at enqueue time, if any. Echoed back on every job-fetch response so callers can observe the exact `when` / `fold` expressions the server is evaluating on subsequent folds (only the first enqueue's config applies for the life of the batch). See the enqueue-request table for the field shape.
`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.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`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 is in-flight.

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

`PUT /jobs/{id}/budgets`

Replace all budgets on the specified job.

Parameters

Field	Description
`id` path string	ID of the job for which to replace budgets.

Request Body

Field	Description
`budgets` required array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs. *Requires a pro* license**.
`budgets[].key` required* string	The identifier for the budget. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`budgets[*].cost` int32	The number of tokens this job takes from the budget. Defaults to 1.
`budgets[*].create_with` object	Specification from which to create this budget atomically with the job if it does not already exist. Without this, the budget must exist or a 422 response will be returned. Does not overwrite any existing budget.
`budgets[].create_with.allocation` required* int32	The total number of tokens available in this budget's pool for use by its configured strategy. No jobs can exist bound to this budget with a `cost` that exceeds the allocation.
`budgets[].create_with.strategy` required* object	Details of the specific strategy that is used to manage the tokens available under this budget.
`budgets[].create_with.strategy.type` required* string	Names the strategy used to manage the tokens within the budget. One of: `while_in_flight` Concurrency control — tokens are spent from the budget when jobs are dispatched to workers, and returned when the job completes or fails, or the worker disconnects uncleanly. For example, for an allocation of 5, at most 5 jobs bound to this budget can be in-flight at any given time. `time_based` Rate limit — tokens are spent from the budget when jobs are dispatched to workers and are only returned after a configured period of time, regardless of the outcome of the job.
`budgets[*].create_with.strategy.duration_ms` int64	Required for `time_based` strategies. Invalid for `while_in_flight`. Specifies the period of time in milliseconds over which a `time_based` rate limit is measured. For example, for an allocation of 1000 and a `duration_ms` of 60000, the rate limit is `1000/minute`.
`budgets[*].create_with.strategy.burst` int32	The maximum number of tokens that may be accumulated at once for a `time_based` budget. Defaults to whatever the configured `allocation` is. So for a `1000/hour` rate limit, the budget would technically permit a short burst of 1000 jobs if no other jobs have used tokens from the budget for a whole hour. Setting a burst of 1 means tokens cannot accumulate and jobs are always paced according to the configured rate limit. It is also possible to intentionally set a burst higher than the configured allocation, such as a burst of 2000 for a `1000/hour` allocation. In this case if the budget has been idle for 2 hours, it would permit a sudden burst of 2000 jobs at any moment. No jobs can exist bound to this budget with a `cost` that exceeds the burst.

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
`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`.
`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.
`folded` required boolean	Only returned on enqueue responses. Set to `true` if this enqueue was folded into an existing pending batched job (see the `batch` object on the request and the Batched jobs section). Folded responses use HTTP `200 OK` rather than `201 Created`.
`batch` object	The batched-job configuration attached at enqueue time, if any. Echoed back on every job-fetch response so callers can observe the exact `when` / `fold` expressions the server is evaluating on subsequent folds (only the first enqueue's config applies for the life of the batch). See the enqueue-request table for the field shape.
`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.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`404` Not Found

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

`422` Unprocessable Entity

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

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

`DELETE /jobs/{id}/budgets`

Remove all budgets from the specified job.

Parameters

Field	Description
`id` path string	ID of the job for which to remove budgets.

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
`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`.
`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.
`folded` required boolean	Only returned on enqueue responses. Set to `true` if this enqueue was folded into an existing pending batched job (see the `batch` object on the request and the Batched jobs section). Folded responses use HTTP `200 OK` rather than `201 Created`.
`batch` object	The batched-job configuration attached at enqueue time, if any. Echoed back on every job-fetch response so callers can observe the exact `when` / `fold` expressions the server is evaluating on subsequent folds (only the first enqueue's config applies for the life of the batch). See the enqueue-request table for the field shape.
`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.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`404` Not Found

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

`422` Unprocessable Entity

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

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

`POST /jobs/budgets/{key}`

Bind a budget to all matching jobs specified by the filter. Jobs that already have the binding are gracefully skipped. Jobs in a terminal status are gracefully skipped. Jobs in the in_flight status are blocked and reported for retry.

Parameters

All options are additive.

Field	Description
`key` path string	The identifier for the budget. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`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`.

Request Body

Field	Description
`cost` int32	The number of tokens the job takes from the budget. Defaults to 1.
`create_with` object	Specification from which to create this budget atomically with the binding if it does not already exist. Without this, the budget must exist or a 422 response will be returned. Does not overwrite any existing budget.
`create_with.allocation` required int32	The total number of tokens available in this budget's pool for use by its configured strategy. No jobs can exist bound to this budget with a `cost` that exceeds the allocation.
`create_with.strategy` required object	Details of the specific strategy that is used to manage the tokens available under this budget.
`create_with.strategy.type` required string	Names the strategy used to manage the tokens within the budget. One of: `while_in_flight` Concurrency control — tokens are spent from the budget when jobs are dispatched to workers, and returned when the job completes or fails, or the worker disconnects uncleanly. For example, for an allocation of 5, at most 5 jobs bound to this budget can be in-flight at any given time. `time_based` Rate limit — tokens are spent from the budget when jobs are dispatched to workers and are only returned after a configured period of time, regardless of the outcome of the job.
`create_with.strategy.duration_ms` int64	Required for `time_based` strategies. Invalid for `while_in_flight`. Specifies the period of time in milliseconds over which a `time_based` rate limit is measured. For example, for an allocation of 1000 and a `duration_ms` of 60000, the rate limit is `1000/minute`.
`create_with.strategy.burst` int32	The maximum number of tokens that may be accumulated at once for a `time_based` budget. Defaults to whatever the configured `allocation` is. So for a `1000/hour` rate limit, the budget would technically permit a short burst of 1000 jobs if no other jobs have used tokens from the budget for a whole hour. Setting a burst of 1 means tokens cannot accumulate and jobs are always paced according to the configured rate limit. It is also possible to intentionally set a burst higher than the configured allocation, such as a burst of 2000 for a `1000/hour` allocation. In this case if the budget has been idle for 2 hours, it would permit a sudden burst of 2000 jobs at any moment. No jobs can exist bound to this budget with a `cost` that exceeds the burst.

Responses

`200` OK

Returns the number of updated jobs, and the list of any job IDs that could not be updated because those jobs were in_flight — in which case those specific IDs may be retried.

Field	Description
`changed` required int64	The number of jobs that were modified in the operation.
`blocked` required array	Array of Job IDs that were not modified because they were `in_flight`. The operation may be retried, including just those IDs in the `id` query parameter.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`422` Unprocessable Entity

When invalid values are provided.

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

`PUT /jobs/budgets/{key}`

Replace budget to all matching jobs specified by the filter. Jobs that already have the binding are updated. Jobs that do not have the binding are given it. Jobs in a terminal status are gracefully skipped. Jobs in the in_flight status are blocked and reported for retry.

Parameters

All options are additive.

Field	Description
`key` path string	The identifier for the budget. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`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`.

Request Body

Field	Description
`cost` int32	The number of tokens the job takes from the budget. Defaults to 1.
`create_with` object	Specification from which to create this budget atomically with the binding if it does not already exist. Without this, the budget must exist or a 422 response will be returned. Does not overwrite any existing budget.
`create_with.allocation` required int32	The total number of tokens available in this budget's pool for use by its configured strategy. No jobs can exist bound to this budget with a `cost` that exceeds the allocation.
`create_with.strategy` required object	Details of the specific strategy that is used to manage the tokens available under this budget.
`create_with.strategy.type` required string	Names the strategy used to manage the tokens within the budget. One of: `while_in_flight` Concurrency control — tokens are spent from the budget when jobs are dispatched to workers, and returned when the job completes or fails, or the worker disconnects uncleanly. For example, for an allocation of 5, at most 5 jobs bound to this budget can be in-flight at any given time. `time_based` Rate limit — tokens are spent from the budget when jobs are dispatched to workers and are only returned after a configured period of time, regardless of the outcome of the job.
`create_with.strategy.duration_ms` int64	Required for `time_based` strategies. Invalid for `while_in_flight`. Specifies the period of time in milliseconds over which a `time_based` rate limit is measured. For example, for an allocation of 1000 and a `duration_ms` of 60000, the rate limit is `1000/minute`.
`create_with.strategy.burst` int32	The maximum number of tokens that may be accumulated at once for a `time_based` budget. Defaults to whatever the configured `allocation` is. So for a `1000/hour` rate limit, the budget would technically permit a short burst of 1000 jobs if no other jobs have used tokens from the budget for a whole hour. Setting a burst of 1 means tokens cannot accumulate and jobs are always paced according to the configured rate limit. It is also possible to intentionally set a burst higher than the configured allocation, such as a burst of 2000 for a `1000/hour` allocation. In this case if the budget has been idle for 2 hours, it would permit a sudden burst of 2000 jobs at any moment. No jobs can exist bound to this budget with a `cost` that exceeds the burst.

Responses

`200` OK

Returns the number of updated jobs, and the list of any job IDs that could not be updated because those jobs were in_flight — in which case those specific IDs may be retried.

Field	Description
`changed` required int64	The number of jobs that were modified in the operation.
`blocked` required array	Array of Job IDs that were not modified because they were `in_flight`. The operation may be retried, including just those IDs in the `id` query parameter.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`422` Unprocessable Entity

When invalid values are provided.

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

`PATCH /jobs/budgets/{key}`

Update the details of the named budget on all matching jobs specified by the filter. Currently only the cost can be patched. Jobs that do not have the binding are gracefull skipped. Jobs that have the binding are updated. Jobs in a terminal status are gracefully skipped. Jobs in the in_flight status are blocked and reported for retry.

Parameters

All options are additive.

Field	Description
`key` path string	The identifier for the budget.
`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`.

Request Body

Field	Description
`cost` required int32	The number of tokens jobs take from the budget.

Responses

`200` OK

Returns the number of updated jobs, and the list of any job IDs that could not be updated because those jobs were in_flight — in which case those specific IDs may be retried.

Field	Description
`changed` required int64	The number of jobs that were modified in the operation.
`blocked` required array	Array of Job IDs that were not modified because they were `in_flight`. The operation may be retried, including just those IDs in the `id` query parameter.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`422` Unprocessable Entity

When invalid values are provided.

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

`DELETE /jobs/budgets/{key}`

Remove the named budget from all matching jobs specified by the filter. Jobs that do not have the binding are gracefull skipped. Jobs that have the binding are updated. Jobs in a terminal status are gracefully skipped. Jobs in the in_flight status are blocked and reported for retry.

Parameters

All options are additive.

Field	Description
`key` path string	The identifier for the budget.
`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

Returns the number of updated jobs, and the list of any job IDs that could not be updated because those jobs were in_flight — in which case those specific IDs may be retried.

Field	Description
`changed` required int64	The number of jobs that were modified in the operation.
`blocked` required array	Array of Job IDs that were not modified because they were `in_flight`. The operation may be retried, including just those IDs in the `id` query parameter.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`422` Unprocessable Entity

When invalid values are provided.

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

`DELETE /jobs/budgets`

Remove all budgets from all matching jobs specified by the filter. Jobs in a terminal status are gracefully skipped. Jobs in the in_flight status are blocked and reported for retry.

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

Returns the number of updated jobs, and the list of any job IDs that could not be updated because those jobs were in_flight — in which case those specific IDs may be retried.

Field	Description
`changed` required int64	The number of jobs that were modified in the operation.
`blocked` required array	Array of Job IDs that were not modified because they were `in_flight`. The operation may be retried, including just those IDs in the `id` query parameter.

`403` Forbidden

When the server is not confiured with a Pro license.

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

`422` Unprocessable Entity

When invalid values are provided.

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

Examples

Update a job’s queue and priority

Request:

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

Response:

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`

Request:

http PATCH 127.0.0.1:7890/jobs/03fvmbsuryhdkxvb6vjy4qhxp --raw '{
    "ready_at": 1775217412000
}'

Response:

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.

Request:

http PATCH 127.0.0.1:7890/jobs/03fvmbsuryhdkxvb6vjy4qhxp --raw '{
    "retry_limit": null
}'

Response:

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

Request:

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

Response:

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

Request:

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

Response:

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.

Find Request:

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

Find Response:

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"
    }
}

Delete Request:

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

Delete Response:

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

{
    "deleted": 2
}

Keyboard shortcuts

Zizq API Reference