Queues

Send and receive messages with Cloudflare Queues

Cloudflare Queues is a global message queuing service. Use the API to create queues, send messages, and manage consumers.

Overview

Access the Queues API:

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
});

// Access Queues resources
const queues = client.queues;

Queues

Manage queue creation and configuration.

Create a queue

Create a new queue.

const queue = await client.queues.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  queue_name: 'my-queue',
});

account_id · string · required

Your Cloudflare account ID

queue_name · string · required

Name for the queue

queue_id · string

The unique identifier for the queue

queue_name · string

The queue name

created_on · string

ISO 8601 timestamp when the queue was created

modified_on · string

ISO 8601 timestamp when the queue was last modified

List queues

Retrieve all queues in your account.

for await (const queue of client.queues.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(queue);
}

account_id · string · required

Your Cloudflare account ID

Get a queue

Retrieve details about a specific queue.

const queue = await client.queues.get(
  '023e105f4ecef8ad9ca31a8372d0c353',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

queue_id · string · required

The queue ID

account_id · string · required

Your Cloudflare account ID

Update a queue

Update queue configuration.

const queue = await client.queues.update(
  '023e105f4ecef8ad9ca31a8372d0c353',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    queue_name: 'updated-queue-name',
    settings: {
      delivery_delay: 0,
      message_retention_period: 345600, // 4 days
    },
  }
);

queue_id · string · required

The queue ID to update

account_id · string · required

Your Cloudflare account ID

queue_name · string

The new queue name

settings · object

Queue settings object

settings.delivery_delay · number

Number of seconds to delay delivery of all messages (0-43200)

settings.message_retention_period · number

Number of seconds to retain unconsumed messages (60-1209600, default: 345600)

settings.delivery_paused · boolean

Whether message delivery to consumers is paused

Delete a queue

Delete a queue.

await client.queues.delete(
  '023e105f4ecef8ad9ca31a8372d0c353',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

queue_id · string · required

The queue ID to delete

account_id · string · required

Your Cloudflare account ID

Messages

Send and receive messages from queues.

Send a message

Send a single message to a queue.

const response = await client.queues.messages.push(
  'my-queue',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    body: JSON.stringify({ hello: 'world' }),
  }
);

queue_id · string · required

The queue ID or name

account_id · string · required

Your Cloudflare account ID

body · string · required

The message body (up to 128 KB)

content_type · string

Content type (default: ‘text/plain’)

Send multiple messages

Send multiple messages in a single request.

const response = await client.queues.messages.bulkPush(
  'my-queue',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    messages: [
      { body: JSON.stringify({ id: 1 }) },
      { body: JSON.stringify({ id: 2 }) },
      { body: JSON.stringify({ id: 3 }) },
    ],
  }
);

queue_id · string · required

The queue ID or name

account_id · string · required

Your Cloudflare account ID

messages · array · required

Array of message objects (up to 100 messages)

Pull messages

Pull messages from a queue (HTTP pull).

const messages = await client.queues.messages.pull(
  'my-queue',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    batch_size: 10,
    visibility_timeout_ms: 30000,
  }
);

queue_id · string · required

The queue ID or name

account_id · string · required

Your Cloudflare account ID

batch_size · number

Number of messages to pull (1-100, default: 10)

visibility_timeout_ms · number

Time in milliseconds to hide messages from other consumers (default: 30000)

Acknowledge messages

Acknowledge messages after processing.

await client.queues.messages.ack(
  'my-queue',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    acks: [
      { lease_id: 'lease-id-1' },
      { lease_id: 'lease-id-2' },
    ],
  }
);

queue_id · string · required

The queue ID or name

account_id · string · required

Your Cloudflare account ID

acks · array · required

Array of acknowledgment objects with lease IDs

Consumers

Manage queue consumers (Workers that process messages).

Create a consumer

Create a Worker consumer for a queue.

const consumer = await client.queues.consumers.create(
  'my-queue',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    script_name: 'my-consumer-worker',
    settings: {
      batch_size: 10,
      max_retries: 3,
      max_wait_time_ms: 5000,
    },
  }
);

queue_id · string · required

The queue ID or name

account_id · string · required

Your Cloudflare account ID

script_name · string · required

Name of the Worker script to process messages

settings · object

Consumer settings

settings.batch_size · number

Number of messages per batch (1-100, default: 10)

settings.max_retries · number

Maximum retry attempts (0-100, default: 3)

settings.max_wait_time_ms · number

Maximum time to wait for messages in milliseconds (default: 5000)

List consumers

Retrieve all consumers for a queue.

for await (const consumer of client.queues.consumers.list(
  'my-queue',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
)) {
  console.log(consumer);
}

Delete a consumer

await client.queues.consumers.delete(
  'my-queue',
  consumerId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Purge

Delete all messages from a queue.

Start purge

await client.queues.purge.start(
  'my-queue',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Check purge status

const status = await client.queues.purge.status(
  'my-queue',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);