Waiting rooms

Manage Cloudflare Waiting Rooms to queue visitors during traffic surges

Waiting Rooms allow you to queue visitors when your website experiences high traffic, ensuring a smooth user experience and protecting your origin servers from being overwhelmed.

Create a waiting room

Creates a new waiting room for a zone.

const waitingRoom = await client.waitingRooms.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  host: 'shop.example.com',
  name: 'production_webinar',
  new_users_per_minute: 200,
  total_active_users: 200,
});

zone_id · string · required

The zone identifier

host · string · required

The hostname to which this waiting room will be applied (no wildcards). The hostname must be the primary domain, subdomain, or custom hostname of this zone.

name · string · required

A unique name to identify the waiting room. Only alphanumeric characters, hyphens, and underscores are allowed.

new_users_per_minute · number · required

The number of new users that will be let into the route every minute.

total_active_users · number · required

The total number of active user sessions on the route at a point in time.

path · string

Sets the path within the host to enable the waiting room on. The waiting room will be enabled for all subpaths as well. Defaults to /.

description · string

A description of the waiting room.

session_duration · number

Lifetime of a cookie (in minutes) set by Cloudflare for users who get access to the route. Defaults to 5 minutes.

disable_session_renewal · boolean

Disables automatic renewal of session cookies. Defaults to false.

suspended · boolean

Suspends the waiting room, allowing all traffic through. Defaults to false.

queue_all · boolean

Whether to queue all visitors, regardless of traffic levels. Defaults to false.

json_response_enabled · boolean

If true, requests to the waiting room with the header Accept: application/json will receive a JSON response object.

custom_page_html · string

Custom HTML to display while users are in the waiting room.

default_template_language · string

The language to use for the default waiting room page. Available languages: de-DE, en-US, es-ES, fr-FR, id-ID, it-IT, ja-JP, ko-KR, nl-NL, pl-PL, pt-BR, tr-TR, zh-CN, zh-TW.

cookie_attributes · object

Configures cookie attributes for the waiting room cookie.

samesite · string

SameSite attribute: auto, lax, none, or strict

secure · string

Secure attribute: auto, always, or never

additional_routes · array

Additional hostname and path combinations to which this waiting room will be applied.

host · string

The hostname for this additional route

path · string

The path for this additional route

id · string

The waiting room identifier

created_on · string

Timestamp when the waiting room was created

modified_on · string

Timestamp when the waiting room was last modified

name · string

The waiting room name

host · string

The hostname where the waiting room is applied

path · string

The path where the waiting room is applied

total_active_users · number

The total number of active user sessions allowed

new_users_per_minute · number

The number of new users admitted per minute

Update a waiting room

Updates a configured waiting room.

const waitingRoom = await client.waitingRooms.update(
  '699d98642c564d2e855e9661899b7252',
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    host: 'shop.example.com',
    name: 'production_webinar',
    new_users_per_minute: 300,
    total_active_users: 300,
  },
);

waitingRoomId · string · required

The waiting room identifier

zone_id · string · required

The zone identifier

List waiting rooms

Lists all waiting rooms for an account or zone.

for await (const waitingRoom of client.waitingRooms.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(waitingRoom.name);
}

zone_id · string

The zone identifier (use either zone_id or account_id)

account_id · string

The account identifier (use either zone_id or account_id)

Get a waiting room

Fetches details for a single configured waiting room.

const waitingRoom = await client.waitingRooms.get(
  '699d98642c564d2e855e9661899b7252',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

waitingRoomId · string · required

The waiting room identifier

zone_id · string · required

The zone identifier

Edit a waiting room

Patches a configured waiting room, updating only the specified fields.

const waitingRoom = await client.waitingRooms.edit(
  '699d98642c564d2e855e9661899b7252',
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    suspended: true,
  },
);

waitingRoomId · string · required

The waiting room identifier

zone_id · string · required

The zone identifier

Delete a waiting room

Deletes a waiting room.

await client.waitingRooms.delete(
  '699d98642c564d2e855e9661899b7252',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

waitingRoomId · string · required

The waiting room identifier

zone_id · string · required

The zone identifier

Preview waiting room

Get a preview of how a waiting room will look.

const preview = await client.waitingRooms.page.preview({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  waiting_room_id: '699d98642c564d2e855e9661899b7252',
});

Waiting room events

Manage scheduled events for waiting rooms to handle predictable traffic surges.

// Create an event
const event = await client.waitingRooms.events.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  waiting_room_id: '699d98642c564d2e855e9661899b7252',
  name: 'Black Friday Sale',
  event_start_time: '2026-11-27T12:00:00Z',
  event_end_time: '2026-11-27T18:00:00Z',
  new_users_per_minute: 500,
  total_active_users: 1000,
});

// List events
for await (const event of client.waitingRooms.events.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  waiting_room_id: '699d98642c564d2e855e9661899b7252',
})) {
  console.log(event.name);
}

Waiting room rules

Manage rules to bypass or customize waiting room behavior.

// Create a rule
const rule = await client.waitingRooms.rules.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  waiting_room_id: '699d98642c564d2e855e9661899b7252',
  action: 'bypass_waiting_room',
  expression: 'http.request.uri.path contains "/admin"',
});

Get waiting room status

Get the current status and metrics for a waiting room.

const status = await client.waitingRooms.statuses.get({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  waiting_room_id: '699d98642c564d2e855e9661899b7252',
});

Waiting room settings

Manage zone-level waiting room settings.

// Get settings
const settings = await client.waitingRooms.settings.get({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

// Update settings
await client.waitingRooms.settings.edit({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  search_engine_crawler_bypass: true,
});