Cron Scheduling

Note

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

Note

This feature requires a Pro license.

The Zizq server supports managing recurring job schedules, through which jobs are enqueued on a cadence described by time zone-aware cron expressions. Workers process these jobs like any other jobs. There is no requirement to allocate a dedicated worker for the purpose of processing recurring jobs.

Collections of cron entries are grouped together into one or more cron groups. Entire groups, and individual entries can be paused and resumed.

The jobs that a cron schedule can enqueue are just like any other job, with the sole exception that they cannot specify ready_at — which would be nonsensical. They can use unique keys, batched jobs, budgets and any future features without restriction.

The API is designed to facilitate clients performing a single PUT operation to define (or redefine) one or more schedules at application startup time. Many clients can all perform this same operation safely. The result is idempotent. Other endpoints are available to support more granular methods of updating cron schedules.

`GET /crons`

Returns a list of available cron groups.

Responses

`200` OK

Field	Description
`crons` required array	Array of cron group names (strings).

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`GET /crons/{group}`

Return the definition for an existing cron group.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.

Responses

`200` OK

Field	Description
`name` required string	Application-defined name that identifies the cron group.
`paused` required boolean	Whether or not this cron group is currently paused. When paused Zizq stops enqueueing jobs within the group, though the scheduler does continue advancing the time. Check the values of `paused_at` and `resumed_at` for details on when the group was last paused/resumed.
`timezone` string	IANA timezone identifier applied to every entry in the group that does not specify one of its own. Absent when the group does not specify one, in which case those entries are evaluated in the system timezone where the Zizq server is running.
`paused_at` int64	Timestamp indicating when this group was marked paused. Resets every time the queue is paused again.
`resumed_at` int64	Timestamp indicating when this group was unpaused. Resets every time the queue is paused again.
`entries` required array	List of entries that will be present within the cron group. Each entry is uniquely identified within the group by an application-defined name.
`entries[].name` required* string	Application-defined identifier for this entry within the group.
`entries[].expression` required* string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision. See the timestamps in `next_enqueue_at` and `last_enqueue_at` for details on future/historical scheduling.
`entries[*].timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`entries[*].paused` boolean	Whether or not this entry is currently paused. When paused Zizq stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. See the values of `paused_at` and `resumed_at` on the entry for details on when the entry was last paused/resumed.
`entries[*].paused_at` int64	Timestamp indicating when this entry was paused. Resets every time the entry is paused again.
`entries[*].resumed_at` int64	Timestamp indicating when this entry was unpaused. Resets every time the entry is paused again.
`entries[*].next_enqueue_at` int64	Timestamp indicating when this entry is next due.
`entries[*].last_enqueue_at` int64	Timestamp indicating when this entry was last enqueued.
`entries[].job` required* object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`entries[].job.queue` required* string	Arbitrary queue name to which the job is assigned.
`entries[].job.type` required* string	Job type known to your application.
`entries[].job.payload` required* object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`entries[*].job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`entries[*].job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary.
`entries[*].job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`entries[*].job.batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`entries[*].job.batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`entries[*].job.batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`entries[*].job.batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`entries[*].job.budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`entries[].job.budgets[].key` required string	The identifier for the budget.
`entries[].job.budgets[].cost` required int32	The number of tokens this job takes from the budget.
`entries[*].job.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.
`entries[*].job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`entries[*].job.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.
`entries[*].job.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.
`entries[*].job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`entries[*].job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`entries[*].job.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.
`entries[*].job.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.

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`404` Not Found

The specified cron group does not exist.

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

`PUT /crons/{group}`

Define a cron group (a collection of cron entries) on the server. This operation is atomic and idempotent. It is intended for use in application startup code. Multiple processes may all call the same endpoint with the same schedule data unconditionally and Zizq is smart enough to handle it safely.

If the schedule does not yet exist, it is created.
If the schedule exists, it is updated in place.
Entries that have not changed are retained, along with all state.
Entries that have been removed are deleted.
Entries that have been modified are replaced.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.
`paused` boolean	Whether or not this cron group should be paused. When paused Zizq sets the `paused_at` timestamp on the group and stops enqueueing jobs within the group, though the scheduler does continue advancing the time. When the value was previously `false` and is set to `true` Zizq sets the `resumed_at` timestamp on the group and re-commences enqueueing jobs for all unpaused entries in the group.
`timezone` string	Optional IANA timezone identifier applied to every entry in the group that does not specify one of its own. When not specified, those entries are evaluated in the system timezone where the Zizq server is running. Because this endpoint replaces the group in full, omitting this field clears any timezone the group previously had.
`entries` required array	List of entries that will be present within the cron group. Each entry is uniquely identified within the group by an application-defined name.
`entries[].name` required* string	Application-defined identifier for this entry within the group.
`entries[].expression` required* string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision.
`entries[*].timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`entries[*].paused` boolean	Whether or not this entry should be paused. When paused Zizq sets the `paused_at` timestamp on the entry and stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. When the value was previously `false` and is set to `true` Zizq sets the `resumed_at` timestamp on the entry and re-commences enqueueing jobs for it.
`entries[].job` required* object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`entries[].job.queue` required* string	Arbitrary queue name to which the job is assigned. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`entries[].job.type` required* string	Job type known to your application. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`entries[].job.payload` required* object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`entries[*].job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`entries[*].job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary.
`entries[*].job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`entries[*].job.batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`entries[*].job.batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`entries[*].job.batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`entries[*].job.batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`entries[*].job.budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`entries[].job.budgets[].key` required string	The identifier for the budget. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`entries[].job.budgets[].cost` int32	The number of tokens this job takes from the budget. Defaults to 1.
`entries[].job.budgets[].create_with` object	Specification from which to create this budget atomically with the cron entry 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.
`entries[].job.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.
`entries[].job.budgets[].create_with.strategy` required object	Details of the specific strategy that is used to manage the tokens available under this budget.
`entries[].job.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.
`entries[].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`.
`entries[].job.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.
`entries[*].job.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.
`entries[*].job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`entries[*].job.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.
`entries[*].job.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.
`entries[*].job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`entries[*].job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`entries[*].job.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.
`entries[*].job.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.

Responses

`200` OK

Field	Description
`name` required string	Application-defined name that identifies the cron group.
`paused` required boolean	Whether or not this cron group is currently paused. When paused Zizq stops enqueueing jobs within the group, though the scheduler does continue advancing the time. Check the values of `paused_at` and `resumed_at` for details on when the group was last paused/resumed.
`timezone` string	IANA timezone identifier applied to every entry in the group that does not specify one of its own. Absent when the group does not specify one, in which case those entries are evaluated in the system timezone where the Zizq server is running.
`paused_at` int64	Timestamp indicating when this group was marked paused. Resets every time the queue is paused again.
`resumed_at` int64	Timestamp indicating when this group was unpaused. Resets every time the queue is paused again.
`entries` required array	List of entries that will be present within the cron group. Each entry is uniquely identified within the group by an application-defined name.
`entries[].name` required* string	Application-defined identifier for this entry within the group.
`entries[].expression` required* string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision. See the timestamps in `next_enqueue_at` and `last_enqueue_at` for details on future/historical scheduling.
`entries[*].timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`entries[*].paused` boolean	Whether or not this entry is currently paused. When paused Zizq stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. See the values of `paused_at` and `resumed_at` on the entry for details on when the entry was last paused/resumed.
`entries[*].paused_at` int64	Timestamp indicating when this entry was paused. Resets every time the entry is paused again.
`entries[*].resumed_at` int64	Timestamp indicating when this entry was unpaused. Resets every time the entry is paused again.
`entries[*].next_enqueue_at` int64	Timestamp indicating when this entry is next due.
`entries[*].last_enqueue_at` int64	Timestamp indicating when this entry was last enqueued.
`entries[].job` required* object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`entries[].job.queue` required* string	Arbitrary queue name to which the job is assigned.
`entries[].job.type` required* string	Job type known to your application.
`entries[].job.payload` required* object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`entries[*].job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`entries[*].job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary.
`entries[*].job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`entries[*].job.batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`entries[*].job.batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`entries[*].job.batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`entries[*].job.batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`entries[*].job.budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`entries[].job.budgets[].key` required string	The identifier for the budget.
`entries[].job.budgets[].cost` required int32	The number of tokens this job takes from the budget.
`entries[*].job.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.
`entries[*].job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`entries[*].job.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.
`entries[*].job.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.
`entries[*].job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`entries[*].job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`entries[*].job.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.
`entries[*].job.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.

`400` Bad Request

Invalid inputs were provided.

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

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`PATCH /crons/{group}`

Update an existing cron group, to pause/resume it or to change the timezone its entries default to.

Fields that are omitted are left unchanged. A field explicitly set to null is cleared.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.
`paused` boolean	Whether or not this cron group should be paused. When paused Zizq sets the `paused_at` timestamp on the group and stops enqueueing jobs within the group, though the scheduler does continue advancing the time. When the value was previously `false` and is set to `true` Zizq sets the `resumed_at` timestamp on the group and re-commences enqueueing jobs for all unpaused entries in the group.
`timezone` string	IANA timezone identifier applied to every entry in the group that does not specify one of its own. Set it to `null` to clear it, which returns those entries to the system timezone where the Zizq server is running. Changing it reschedules every entry that inherits it; entries that specify their own timezone are unaffected.

Responses

`200` OK

Field	Description
`name` required string	Application-defined name that identifies the cron group.
`paused` required boolean	Whether or not this cron group is currently paused. When paused Zizq stops enqueueing jobs within the group, though the scheduler does continue advancing the time. Check the values of `paused_at` and `resumed_at` for details on when the group was last paused/resumed.
`timezone` string	IANA timezone identifier applied to every entry in the group that does not specify one of its own. Absent when the group does not specify one, in which case those entries are evaluated in the system timezone where the Zizq server is running.
`paused_at` int64	Timestamp indicating when this group was marked paused. Resets every time the queue is paused again.
`resumed_at` int64	Timestamp indicating when this group was unpaused. Resets every time the queue is paused again.
`entries` required array	List of entries that will be present within the cron group. Each entry is uniquely identified within the group by an application-defined name.
`entries[].name` required* string	Application-defined identifier for this entry within the group.
`entries[].expression` required* string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision. See the timestamps in `next_enqueue_at` and `last_enqueue_at` for details on future/historical scheduling.
`entries[*].timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`entries[*].paused` boolean	Whether or not this entry is currently paused. When paused Zizq stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. See the values of `paused_at` and `resumed_at` on the entry for details on when the entry was last paused/resumed.
`entries[*].paused_at` int64	Timestamp indicating when this entry was paused. Resets every time the entry is paused again.
`entries[*].resumed_at` int64	Timestamp indicating when this entry was unpaused. Resets every time the entry is paused again.
`entries[*].next_enqueue_at` int64	Timestamp indicating when this entry is next due.
`entries[*].last_enqueue_at` int64	Timestamp indicating when this entry was last enqueued.
`entries[].job` required* object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`entries[].job.queue` required* string	Arbitrary queue name to which the job is assigned.
`entries[].job.type` required* string	Job type known to your application.
`entries[].job.payload` required* object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`entries[*].job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`entries[*].job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary.
`entries[*].job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`entries[*].job.batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`entries[*].job.batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`entries[*].job.batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`entries[*].job.batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`entries[*].job.budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`entries[].job.budgets[].key` required string	The identifier for the budget.
`entries[].job.budgets[].cost` required int32	The number of tokens this job takes from the budget.
`entries[*].job.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.
`entries[*].job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`entries[*].job.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.
`entries[*].job.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.
`entries[*].job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`entries[*].job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`entries[*].job.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.
`entries[*].job.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.

`400` Bad Request

Invalid inputs were provided.

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

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`404` Not Found

The specified cron group does not exist.

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

`DELETE /crons`

Delete every cron group and its entries in a single request. Returns the number of groups removed.

Responses

`200` OK

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

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`DELETE /crons/{group}`

Delete an entire cron group and its entries.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.

Responses

`204` No Content

No response body included for a successful response.

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`404` Not Found

The specified cron group does not exist.

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

`GET /crons/{group}/entries/{entry}`

Get the definition of an individual entry within a cron group.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.
`entry` path string	Application-defined name that identifies the entry within the group.

Responses

`200` OK

Field	Description
`name` required string	Application-defined identifier for this entry within the group.
`expression` required string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision. See the timestamps in `next_enqueue_at` and `last_enqueue_at` for details on future/historical scheduling.
`timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`paused` boolean	Whether or not this entry is currently paused. When paused Zizq stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. See the values of `paused_at` and `resumed_at` on the entry for details on when the entry was last paused/resumed.
`paused_at` int64	Timestamp indicating when this entry was paused. Resets every time the entry is paused again.
`resumed_at` int64	Timestamp indicating when this entry was unpaused. Resets every time the entry is paused again.
`next_enqueue_at` int64	Timestamp indicating when this entry is next due.
`last_enqueue_at` int64	Timestamp indicating when this entry was last enqueued.
`job` required object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`job.queue` required string	Arbitrary queue name to which the job is assigned.
`job.type` required string	Job type known to your application.
`job.payload` required object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary.
`job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`job.batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`job.batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`job.batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`job.batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`job.budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`job.budgets[].key` required* string	The identifier for the budget.
`job.budgets[].cost` required* int32	The number of tokens this job takes from the budget.
`job.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.
`job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`job.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.
`job.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.
`job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`job.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.
`job.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.

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`404` Not Found

The specified entry does not exist.

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

`PUT /crons/{group}/entries/{entry}`

Define an entry within a cron group on the server. The group does not need to pre-exist — it will be automatically created when the first entry is created within it. This operation is atomic and idempotent when given the same entry.

Entries that have not changed are retained, along with all state.
Entries that have been modified are replaced.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.
`entry` path string	Application-defined name that identifies the entry within the group.
`name` required string	Application-defined identifier for this entry within the group. This should be the same as the `entry` value in the path.
`expression` required string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision.
`timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`paused` boolean	Whether or not this entry should be paused. When paused Zizq sets the `paused_at` timestamp on the entry and stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. When the value was previously `false` and is set to `true` Zizq sets the `resumed_at` timestamp on the entry and re-commences enqueueing jobs for it.
`job` required object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`job.queue` required string	Arbitrary queue name to which the job is assigned. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`job.type` required string	Job type known to your application. Must be valid UTF-8 and must not contain any of the follow reserved characters: `,`, `*`, `?`, `[`, `]`, `{`, `}`, `\`.
`job.payload` required object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary. *Requires a pro* license**.
`job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`job.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.
`job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`job.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.
`job.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.
`job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`job.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.
`job.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.

Responses

`200` OK

Field	Description
`name` required string	Application-defined identifier for this entry within the group.
`expression` required string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision. See the timestamps in `next_enqueue_at` and `last_enqueue_at` for details on future/historical scheduling.
`timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`paused` boolean	Whether or not this entry is currently paused. When paused Zizq stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. See the values of `paused_at` and `resumed_at` on the entry for details on when the entry was last paused/resumed.
`paused_at` int64	Timestamp indicating when this entry was paused. Resets every time the entry is paused again.
`resumed_at` int64	Timestamp indicating when this entry was unpaused. Resets every time the entry is paused again.
`next_enqueue_at` int64	Timestamp indicating when this entry is next due.
`last_enqueue_at` int64	Timestamp indicating when this entry was last enqueued.
`job` required object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`job.queue` required string	Arbitrary queue name to which the job is assigned.
`job.type` required string	Job type known to your application.
`job.payload` required object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary.
`job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`job.batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`job.batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`job.batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`job.batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`job.budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`job.budgets[].key` required* string	The identifier for the budget.
`job.budgets[].cost` required* int32	The number of tokens this job takes from the budget.
`job.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.
`job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`job.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.
`job.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.
`job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`job.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.
`job.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.

`400` Bad Request

Invalid inputs were provided.

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

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`PATCH /crons/{group}/entries/{entry}`

Update an existing entry within a cron group. Currently only used to pause/resume the individual entry.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.
`entry` path string	Application-defined name that identifies the entry within the group.
`paused` boolean	Whether or not this entry should be paused. When paused Zizq sets the `paused_at` timestamp on the entry and stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. When the value was previously `false` and is set to `true` Zizq sets the `resumed_at` timestamp on the entry and re-commences enqueueing jobs for it.

Responses

`200` OK

Field	Description
`name` required string	Application-defined identifier for this entry within the group.
`expression` required string	Either a 5-field or a 6-field cron expression (e.g. `/15 0-6 * *`). 6-field expressions enable second-level precision. See the timestamps in `next_enqueue_at` and `last_enqueue_at` for details on future/historical scheduling.
`timezone` string	Optional IANA timezone identifier in which the cron expression should be evaluated. When not specified, the expression is evaluated in the group's `timezone`, or in the system timezone where the Zizq server is running when the group does not specify one either.
`paused` boolean	Whether or not this entry is currently paused. When paused Zizq stops enqueueing jobs for that entry, though the scheduler does continue advancing the time. See the values of `paused_at` and `resumed_at` on the entry for details on when the entry was last paused/resumed.
`paused_at` int64	Timestamp indicating when this entry was paused. Resets every time the entry is paused again.
`resumed_at` int64	Timestamp indicating when this entry was unpaused. Resets every time the entry is paused again.
`next_enqueue_at` int64	Timestamp indicating when this entry is next due.
`last_enqueue_at` int64	Timestamp indicating when this entry was last enqueued.
`job` required object	Details equivalent to those used for enqueueing jobs normally, to be used when the scheduler enqueues jobs for this entry.
`job.queue` required string	Arbitrary queue name to which the job is assigned.
`job.type` required string	Job type known to your application.
`job.payload` required object	Any valid JSON type to be associated with the job, used by the worker when handling the job.
`job.priority` int16	Optional numeric priority for the job. Lower values are processed first (higher priority). The default value is `32768`.
`job.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. Uniqueness is status-bound, not time-bound. There is no arbitrary expiry. Conflicting enqueues do not produce errors, but instead behave idempotently. A success response is returned with details of the existing matching job, and its `duplicate` field set to `true`. This key is intentionally global across all queues and job types. Clients should prefix it as necessary.
`job.unique_while` string	When the job has a unique key, specifies the scope within which that job is considered unique. One of: `queued` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled` or `ready` statuses. `active` Other jobs with the same `unique_key` will not be enqueued while this job is in the `scheduled`, `ready` or `in_flight` statuses. `exists` Other jobs with the same `unique_key` will not be enqueued for as long as this job exists (i.e. until this job is reaped, according to the retention policy). The default scope is `queued`.
`job.batch` object	Optional batched-job configuration. When present, subsequent enqueues sharing the same `batch.key` are folded into this job's pending payload via the `when` and `fold` jq expressions, rather than creating separate pending jobs. All three inner fields are required when this field is set. Mutually exclusive with `unique_key` — supplying both returns `400 Bad Request`.
`job.batch.key` string	Identifies the batch. Only one unsealed batched job exists per key at a time. Enqueues sharing this key fold into the existing pending job (or start a new one if none exists or the existing batch was already sealed).
`job.batch.when` string	jq predicate that decides whether an incoming enqueue folds into the existing pending job. Evaluated with `$existing` bound to the current pending payload and `$new` bound to the incoming payload. Truthy means fold; falsy seals the existing batch and starts a fresh one from the incoming enqueue. Invalid jq syntax, or an expression that returns multiple outputs, returns `422 Unprocessable Entity`.
`job.batch.fold` string	jq expression that produces the merged payload when a fold occurs. Runs with the same `$existing` and `$new` bindings as `when`. Must produce exactly one output; multiple outputs return `422 Unprocessable Entity`.
`job.budgets` array	Array of budget bindings used to control concurrency and/or rate limiting of dispatched jobs.
`job.budgets[].key` required* string	The identifier for the budget.
`job.budgets[].cost` required* int32	The number of tokens this job takes from the budget.
`job.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.
`job.backoff.base_ms` int32	The minimum delay in milliseconds between job retries.
`job.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.
`job.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.
`job.retry_limit` int32	Overrides the severs default retry limit for this job. Once this limit is reached, the server marks the job `dead`.
`job.retention` object	Optional retention policy for `dead` and `completed` jobs which overrides the server's default policy. All fields are optional.
`job.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.
`job.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.

`400` Bad Request

Invalid inputs were provided.

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

`403` Forbidden

Returned when the server is not configured with a pro license.

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

`404` Not Found

The specified entry does not exist.

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

`DELETE /crons/{group}/entries/{entry}`

Delete an individual entry from a cron group.

Parameters

Field	Description
`group` path string	Application-defined name that identifies the cron group.
`entry` path string	Application-defined name that identifies the entry within the group.

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

`404` Not Found

The specified entry does not exist.

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

Examples

List Cron Groups

Request:

http 127.0.0.1:7890/crons

Response:

HTTP/1.1 200 OK
content-length: 31
content-type: application/json
date: Tue, 05 May 2026 02:54:26 GMT

{
    "crons": [
        "group-1",
        "group-2"
    ]
}

Define or Redefine a Cron Group

This makes sense to be a step in application startup.

Request:

http PUT 127.0.0.1:7890/crons/default --raw '{
    "entries": [
        {
            "name": "refresh_data_warehouse",
            "expression": "0 6 * * *",
            "timezone": "Europe/Rome",
            "job": {
                "queue": "data_warehouse",
                "type": "refresh_data_warehouse",
                "priority": 1000,
                "payload": {
                    "incremental": true
                }
            }
        },
        {
            "name": "expire_access_tokens",
            "expression": "*/15 * * * *",
            "job": {
                "queue": "identity",
                "type": "expire_access_tokens",
                "payload": {},
                "unique_key": "expire_access_tokens",
                "unique_while": "active"
            }
        }
    ]
}'

Response:

HTTP/1.1 200 OK
content-length: 606
content-type: application/json
date: Tue, 05 May 2026 04:00:07 GMT

{
    "entries": [
        {
            "expression": "0 6 * * *",
            "job": {
                "payload": {
                    "incremental": true
                },
                "priority": 1000,
                "queue": "data_warehouse",
                "type": "refresh_data_warehouse"
            },
            "last_enqueue_at": 1777953600001,
            "name": "refresh_data_warehouse",
            "next_enqueue_at": 1778040000000,
            "paused": false,
            "timezone": "Europe/Rome"
        },
        {
            "expression": "*/15 * * * *",
            "job": {
                "payload": {},
                "priority": 32768,
                "queue": "identity",
                "type": "expire_access_tokens",
                "unique_key": "expire_access_tokens",
                "unique_while": "active"
            },
            "last_enqueue_at": 1777953600002,
            "name": "expire_access_tokens",
            "next_enqueue_at": 1777954500000,
            "paused": false
        }
    ],
    "name": "default",
    "paused": false
}

Pause an Entry Within a Schedule

Request:

http PATCH 127.0.0.1:7890/crons/default/entries/refresh_data_warehouse --raw '{
    "paused": true
}'

Response:

HTTP/1.1 200 OK
content-length: 299
content-type: application/json
date: Tue, 05 May 2026 04:02:43 GMT

{
    "expression": "0 6 * * *",
    "job": {
        "payload": {
            "incremental": true
        },
        "priority": 1000,
        "queue": "data_warehouse",
        "type": "refresh_data_warehouse"
    },
    "last_enqueue_at": 1777953600001,
    "name": "refresh_data_warehouse",
    "next_enqueue_at": 1778040000000,
    "paused": true,
    "paused_at": 1777953763596,
    "timezone": "Europe/Rome"
}

Resume an Entry Within a Schedule

Request:

http PATCH 127.0.0.1:7890/crons/default/entries/refresh_data_warehouse --raw '{
    "paused": false
}'

Response:

HTTP/1.1 200 OK
content-length: 327
content-type: application/json
date: Tue, 05 May 2026 04:03:40 GMT

{
    "expression": "0 6 * * *",
    "job": {
        "payload": {
            "incremental": true
        },
        "priority": 1000,
        "queue": "data_warehouse",
        "type": "refresh_data_warehouse"
    },
    "last_enqueue_at": 1777953600001,
    "name": "refresh_data_warehouse",
    "next_enqueue_at": 1778040000000,
    "paused": false,
    "paused_at": 1777953763596,
    "resumed_at": 1777953820667,
    "timezone": "Europe/Rome"
}

Delete a Schedule

Request:

http DELETE 127.0.0.1:7890/crons/default

Response:

HTTP/1.1 204 No Content
date: Tue, 05 May 2026 04:04:37 GMT

Keyboard shortcuts

Zizq API Reference