Skip to content

Process work in the background with a queue ​

A queue holds messages until its consumer takes them, a batch at a time. The consumer is either a function runtime, which runs on the background runner, or an HTTPS endpoint of your own. Use a queue when work arrives faster than you want to do it, when it can wait a few seconds, or when it should be retried if it fails.

A queue does not change the live site. Sending, consuming and deleting messages touch only the queue.

Throughout, the distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38) and the function runtime that consumes the queue is 01JBQZ8XKT4A9WN2CDEFGH5RM7.

1. Write the consumer ​

The consumer gets a POST to /_jobs/queue/{name}. The body lists the batch's messages, oldest first:

json
{
  "type": "queue",
  "job_id": "job_01M4X7T2K9Q0V3B8N6C5D1E2F3",
  "attempt": 1,
  "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
  "queue": { "id": "que_01M4XB7Q2W8E5R3T6Y9U1I4O0P", "name": "orders" },
  "messages": [
    { "id": "msg_01M4XB9D3F6G8H1J4K7L0Z2X5C", "body": { "order": 42 }, "attempt": 1, "created_at": "2026-10-19T03:12:09+00:00" }
  ]
}

Answer 2xx to acknowledge the whole batch: Edge deletes those messages. To retry some of them, answer 2xx with the ones to try again; any message you do not list is acknowledged.

js
function handler(request, env) {
  const { messages } = JSON.parse(request.body);
  const retry = [];
  for (const message of messages) {
    if (!sendInvoice(message.body.order)) retry.push({ id: message.id, delay_seconds: 300 });
  }
  return { statusCode: 200, body: JSON.stringify({ retry }) };
}

Any other answer (a 4xx or 5xx, a crash, a timeout) retries every message in the batch, with a growing delay. Delivery is at least once, so a message can arrive twice: key what you do on message.id. Background jobs explains why.

2. Create the queue ​

text
On acme-marketing, create a queue named orders consumed by function
01JBQZ8XKT4A9WN2CDEFGH5RM7, 25 messages a batch, 5 tries before giving up.
bash
edge queues create acme-marketing --name orders --function 01JBQZ8XKT4A9WN2CDEFGH5RM7 \
  --batch-size 25 --max-attempts 5
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/queues \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "orders",
        "consumer": {"type": "wasm", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7"},
        "batch_size": 25,
        "max_attempts": 5
      }'

The agent runs edge_queue_create:

json
{
  "queue_id": "que_01M4XB7Q2W8E5R3T6Y9U1I4O0P",
  "name": "orders",
  "consumer": { "type": "wasm", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7" },
  "batch_size": 25,
  "batch_wait_seconds": 5,
  "concurrency": 2,
  "max_attempts": 5,
  "retention_days": 4,
  "paused": false,
  …
}

A batch goes as soon as it is full, or when its oldest message has waited batch_wait_seconds. concurrency is how many batches can run at once.

To have your own server consume the queue instead, give it an HTTPS URL: --webhook https://crm.example.com/edge-batches, or "consumer": {"type": "webhook", "url": "https://crm.example.com/edge-batches"}. The answer then includes a signing_secret, shown once. Each batch arrives with the same body as above, signed the same way as Edge webhooks, and any 2xx acknowledges the whole batch.

3. Send messages ​

text
Send {"order": 42} to the orders queue on acme-marketing, with idempotency key order-42.
bash
edge queues send que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --body '{"order": 42}' --key order-42
# or many at once, one {"body": …} per line:
edge queues send que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --file orders.jsonl
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/messages \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"body": {"order": 42}, "idempotency_key": "order-42"}]}'

The agent runs edge_queue_send:

json
{
  "queue_id": "que_01M4XB7Q2W8E5R3T6Y9U1I4O0P",
  "messages": [{ "message_id": "msg_01M4XB9D3F6G8H1J4K7L0Z2X5C", "duplicate": false }]
}

Sending the same idempotency_key again while that message is still in the queue returns the same message_id with duplicate: true and adds nothing. Add delay_seconds (up to 7 days) to hold a message back — a reminder that should go out in three days is one message with "delay_seconds": 259200.

A server or CI job that only sends needs a personal access token with queue.send alone. It can send, but cannot read or delete messages.

A cron can also send to a queue on a schedule: give it the target {"type": "enqueue", "queue": "orders"} (--enqueue orders in the CLI). See Run a function on a schedule.

4. Watch it drain ​

In the web app, open Distributions and select acme-marketing. Queues shows each queue's consumer, how many messages are waiting, in a batch, or dead, and how long the oldest has waited. Pause stops new batches (batches already running finish); Resume starts them again. Background jobs lists each batch run.

text
How is the orders queue on acme-marketing doing?
bash
edge queues stats que_01M4XB7Q2W8E5R3T6Y9U1I4O0P
edge queues runs que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status failed
bash
curl -s https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/stats \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_queue_stats and edge_queue_runs:

json
{
  "depth": { "ready": 140, "delayed": 3, "leased": 25, "dead": 0 },
  "oldest_ready_age_seconds": 12,
  "batches_in_flight": 2,
  "last_hour": { "batches_succeeded": 58, "batches_failed": 1, "batch_failure_rate": 0.0169, "dead_lettered": 0 }
}

Subscribe a webhook to queue.backlog.high to hear when a queue holds more than 10,000 messages or its oldest message has waited over an hour.

Hand off work from an endpoint ​

A function behind /_api can send to the queue itself and answer the visitor straight away; the consumer does the slow part later. First let the function send to the queue:

text
Let function 01JBQZ8XKT4A9WN2CDEFGH5RM7 send to the orders queue on acme-marketing.
bash
edge queues update que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --senders 01JBQZ8XKT4A9WN2CDEFGH5RM7
bash
curl -s -X PATCH https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"senders": ["01JBQZ8XKT4A9WN2CDEFGH5RM7"]}'

The agent runs edge_queue_update. Then, in the function:

js
function handler(request, env) {
  const order = JSON.parse(request.body);
  const { id } = env.queue.send('orders', order, { idempotencyKey: `order-${order.id}` });
  return { statusCode: 202, body: JSON.stringify({ queued: id }) };
}

A function may send 10 messages per visitor request. A function that is not in senders gets an error with code denied. Function runtimes has the full method list.

Next ​

When a message runs out of tries, it is kept as a dead message: Handle failed queue messages.