Skip to content
Delay Docs

Queues

A queue holds the settings that all of its jobs share: how long to wait for a response, when to retry, how many jobs run at once and how long failed jobs are kept. The job carries the request itself (URL, method, headers, payload, callback URL). A queue has no URL of its own.

Example

You send a job to a queue by name:

Terminal window
curl -X POST https://app.delay.run/api/jobs \
  -H "Authorization: Bearer $DELAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"queue": "emails", "url": "https://api.yourapp.com/send-welcome", "payload": {"user_id": 42}}'

If your current team has no queue called emails, this call creates one with the defaults below. The job then runs with a 30 second timeout and up to 3 retries. To change that, edit the queue in the dashboard (Set up a queue).

Settings

This is the full list. You change these on the queue’s edit page in the dashboard; the API can’t set them.

SettingDefaultAllowed valuesWhat it does
Queue name-Up to 255 characters, unique in the teamThe name you pass as queue in the API.
Request timeout30 seconds1 to 300 secondsHow long Delay waits for a response. After that, the attempt fails with a timeout.
Enable automatic retriesOnOn or offWhen off, a job’s first failure sends it straight to the dead letter queue.
Retry delays60, 1800, 10800 secondsUp to 10 delays, each 1 to 86,400 secondsThe wait before each retry. See Retries.
Max concurrent jobsEmpty (unlimited)1 to 1000How many of the queue’s jobs may run at the same time.
Dead letter retention14 days3, 7, 14 or 30 daysHow long dead-lettered jobs are kept before automatic cleanup.
Success assertionsNoneUp to 10Checks that a 2xx response must also pass. See Success assertions.
Enable this queueOnOn or offOff pauses the queue. See Pausing a queue.
Enable email alerts for job failuresOnOn or offTurns all of the queue’s alerts on or off: in-app, email and Slack or Discord. See Alerts.

Delay reads these settings each time an attempt starts. An edit applies to the next attempt, including jobs that are already waiting. Retries that are already scheduled keep their start time.

Queues created by the API

POST /api/jobs looks up the queue name in your current team. If there’s no match, it creates the queue with the defaults above.

  • A typo in the name creates a second queue with default settings. It is not an error.
  • To give the very first job custom settings, create the queue in the dashboard first and use its exact name.
  • The API can’t create, list or configure queues.

Retries

When an attempt fails and retries are on, Delay schedules the next attempt after the next delay in Retry delays. Delays are used in order, one per retry, so a job gets 1 attempt plus one per delay.

With the default delays a job gets 4 attempts:

AttemptStartsTime since attempt 1 failed
1At the job’s scheduled time-
21 minute after attempt 1 failsAbout 1 min
330 minutes after attempt 2 failsAbout 31 min
43 hours after attempt 3 failsAbout 3 h 31 min

If attempt 4 also fails, the job is dead-lettered. The times add up the delays only; each attempt’s own duration (up to the timeout) comes on top.

  • Each delay counts from the moment the previous attempt failed.
  • There is no exponential backoff and no jitter. A Retry-After header from your endpoint is ignored.
  • A queue allows at most 10 retries, each up to 24 hours.

What counts as a failure, and why each retry is a new job with a new id: Jobs. Choosing delays: Retries and queue design.

Max concurrent jobs

Set Max concurrent jobs when the endpoint can only handle a few requests at once. When the queue is at its limit, ready jobs stay Pending. Delay checks for free slots once a minute, so a job that waited for a slot can start up to about a minute after one opens.

The limit is applied when Delay hands jobs to its workers. Jobs created at the same moment can all start before the count catches up, so treat it as a soft cap, not a guarantee.

Pausing a queue

Untick Enable this queue on the queue’s edit page to pause it.

  • The API still accepts jobs for a paused queue. The Create job dialog doesn’t list paused queues.
  • Jobs that come due are held as Pending. They don’t fail and don’t use up retries.
  • An attempt that was already running finishes normally.
  • When you tick the box again, held jobs that are due start within about a minute.

The queues list shows a paused queue as Paused. The queue’s own page shows Inactive.

Dead letter retention

A job whose last attempt fails is dead-lettered and listed under Dead letters. Once a day at 00:00 UTC, Delay deletes dead-lettered jobs older than the queue’s Dead letter retention. The dead letter queue can’t be turned off. Replaying and purging: Replay failed jobs.

Next steps