Cloudflare Waiting Room — Queue Management for High-Traffic Events

In this tutorial, you'll learn about Cloudflare Waiting Room. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Cloudflare Waiting Room queues visitors during traffic surges so your origin servers never exceed capacity. This tutorial covers queue configuration, threshold tuning, session management, and integration with other Cloudflare features for high-traffic events.

Why Waiting Room Matters

When a popular product launches or a time-sensitive event goes live, traffic can spike 10x to 100x above normal. Without a waiting room, your origin servers either crash under load or you are forced to serve a generic error page. Cloudflare Waiting Room holds excess visitors in a configurable queue and admits them gradually as capacity becomes available.

Real-world use: DodaZIP runs a annual free compression tool giveaway. In previous years the origin servers crashed within three minutes of the announcement. After deploying Cloudflare Waiting Room with a maximum active users threshold of 5,000, the queue held 42,000 visitors in line and admitted them smoothly over four hours with zero origin errors.

How Waiting Room Works

flowchart TD
  V[Visitor] --> WR{Waiting Room Active?}
  WR -->|Under threshold| ORIGIN[Serve from origin]
  WR -->|Over threshold| QUEUE[Join waiting queue]
  QUEUE --> POSITION[Show queue position]
  POSITION --> ADMIT{Admitted?}
  ADMIT -->|Yes| ORIGIN
  ADMIT -->|No| POSITION
  style WR fill:#f90,color:#fff
  style QUEUE fill:#09c,color:#fff
  style ORIGIN fill:#090,color:#fff

When traffic exceeds the configured threshold, new visitors enter a virtual queue. They see a branded waiting page with their estimated wait time. As active users leave or expire, queued users are admitted in first-come-first-served order.

Configuration through Dashboard

Waiting Room is configured under Traffic > Waiting Room in the Cloudflare dashboard.

# Create a Waiting Room via API
curl -X POST https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-launch",
    "description": "Queue for annual product launch event",
    "host": "shop.example.com",
    "path": "/checkout",
    "new_users_per_minute": 200,
    "total_active_users": 5000,
    "session_duration": 60,
    "queueing_method": "fifo",
    "cookie_suffix": "launch2026",
    "enable_random_queuing": false
  }'

# Response includes the waiting room ID for future updates

# Update an existing Waiting Room configuration
curl -X PATCH https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms/{wr_id} \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "total_active_users": 8000,
    "new_users_per_minute": 300
  }'

# Adjust thresholds based on observed traffic and origin capacity

Queue Thresholds and Tuning

Two thresholds control how many users access your origin simultaneously.

# Calculate appropriate thresholds based on origin capacity
# If your origin handles 10,000 requests per minute at peak
# and each user generates an average of 2 requests per minute:
# total_active_users = 10000 / 2 = 5000
# Factor in 50% headroom: total_active_users = 2500
# new_users_per_minute = total_active_users / 5 = 500

# Enable pre-queueing for scheduled events
# This allows users to queue up before the event starts
# Configuration:
# "queueing_method": "fifo",
# "pre_queue_start_time": "2026-12-01T08:00:00Z",
# "event_start_time": "2026-12-01T09:00:00Z",
# Users who join the pre-queue at 08:00 are admitted first at 09:00

Session Management

Waiting Room uses cookies to track active sessions and queue position.

# Session cookie behavior
# Queue cookie: __cf_wr_q_{suffix} - tracks queue position
# Active cookie: __cf_wr_a_{suffix} - tracks active session
# Both are HttpOnly, Secure, SameSite=Lax

# Custom session duration for different paths
# Set session_duration based on expected user behavior:
# Checkout page: 30-60 minutes (users need time to complete purchase)
# Ticket booking: 10-15 minutes (quick transaction expected)
# Content download: 120 minutes (large file downloads take time)

Branding the Waiting Room Page

You can customize the waiting page with your logo, colors, and messaging.

# Custom HTML template for waiting room page
# Supported template variables:
# {{ waitTime }} - estimated wait time in minutes
# {{ queuePosition }} - user's position in queue
# {{ totalQueue }} - total users in queue
# {{ waitingRoomName }} - name of the waiting room
# Place these in the custom HTML field in the dashboard

# JSON configuration for custom waiting room page
# Upload via API:
# {
#   "custom_template": "<!DOCTYPE html><html><head><title>You are in line</title></head><body><h1>Estimated wait: {{ waitTime }} minutes</h1><p>Your position: {{ queuePosition }} of {{ totalQueue }}</p></body></html>"
# }
# Provide a friendly experience while users wait

FAQ

Practice Questions

1. What are the two primary thresholds that control how many users reach the origin?
2. How does session duration affect the user admission rate?
3. What happens to API requests when the waiting room is active?

Summary

Cloudflare Waiting Room protects your origin during traffic surges by queuing excess visitors and admitting them gradually. Configure total active users and new users per minute thresholds based on your origin capacity, customize the waiting page with your branding, and use session duration tuning to match user behavior patterns. Waiting Room integrates with Cloudflare Load Balancer and works for both HTML pages and API endpoints.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro — security-first tools for the modern web.