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 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.
`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 system timezone where the Zizq server is running.
`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. *Requires a pro* license**.
`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.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.
`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 system timezone where the Zizq server is running.
`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. *Requires a pro* license**.
`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.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.
`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 system timezone where the Zizq server is running.
`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. *Requires a pro* license**.
`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.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. Currently only used to pause/resume the group.

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.

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.
`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 system timezone where the Zizq server is running.
`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. *Requires a pro* license**.
`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.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/{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 system timezone where the Zizq server is running.
`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. *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.

`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 system timezone where the Zizq server is running.
`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 system timezone where the Zizq server is running.
`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. *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.

`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 system timezone where the Zizq server is running.
`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. *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.

`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

http 127.0.0.1:7890/crons

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.

http PUT 127.0.0.1:7890/crons/default <<'JSON'
{
    "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"
            }
        }
    ]
}
JSON

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

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

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

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

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

http DELETE 127.0.0.1:7890/crons/default

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

Keyboard shortcuts

Zizq API Reference