Skip to content
Waiting Room
Visit Waiting Room on GitHub
Set theme to dark (⇧+D)

Create a waiting room via the API

Create a waiting room by appending the following endpoint in the Waiting Room API to the Cloudflare API base URL.

POST zones/{zone_identifier}/waiting_rooms

The Cloudflare API base URL is:

For authentication instructions, see Getting Started: Requests in the Cloudflare API documentation.

For help with endpoints and pagination, see Getting Started: Endpoints.

Configure your waiting room with the following required parameters in the data field:

  • name - A unique name for the waiting room. Use only alphanumeric characters, hyphens, and underscores.
  • host - Host name for which you want to configure a waiting room.
  • total_active_users - The total number of active user sessions on the route at a point in time.
  • new_users_per_minute - The number of new users gaining entry into the route every minute.

The following parameters are optional:

  • path - The path within the host for which you want to configure a waiting room. The waiting room will be enabled for all subpaths as well.
  • description - A description of the the waiting room.
  • session_duration - Lifetime of a cookie (in minutes) set by Cloudflare for users who get access to the route.
  • custom_page_html - HTML code to customize the appearance of your waiting room. Cloudflare provides a sample HTML template that enables the display of estimated wait time on the waiting room page. The default waiting room is used if custom_page_html is not specified. See Waiting Room API properties.


The following example API request configures a waiting room.

curl -X POST "{zone-id}/waiting_rooms" \     -H "X-Auth-Email:" \     -H "X-Auth-Key: xxxxxxxx" \     -H "Content-Type: application/json" \     --data '{"name":"shop_waiting_room",              "description":"Waiting room for webshop",              "host":"",              "path":"/shop",              "new_users_per_minute":200,              "total_active_users":300,              "session_duration":1              }'

The response for the request above is:

{  "success": true,  "errors": [],  "messages": [],  "result": [    {      "id": "1111111111111111111111",      "created_on": "2014-01-01T05:20:00.12345Z",      "modified_on": "2014-01-01T05:20:00.12345Z",      "name": "shop_waiting_room",      "description": "Waiting room for webshop",      "host": "",      "path": "/shop",      "new_users_per_minute": 200,      "total_active_users": 300,      "session_duration": 1    }  ]}

Customize a waiting room web page

You can use the Waiting Room API to customize the web page served to visitors when they are placed in a virtual waiting room.

In the following PATCH request, the custom_page_html field contains the HTML code for the customized waiting room:

curl -X PATCH "{zone-id}/waiting_rooms/{waiting-room-id}"     -H "X-Auth-Email:"     -H "X-Auth-Key: xxxxxxxx"     -H "Content-Type: application/json"     --data '{"custom_page_html":"<p>Include custom HTML here</p>"}'
{  "success": true,  "errors": [],  "messages": [],  "result": [    {      "id": "1111111111111111111111",      "name": "webshop-waiting-room",      "description": "Waiting room for webshop",      "host": "",      "path": "/shop",      "suspended": false,      "queue_all": false,      "new_users_per_minute": 200,      "total_active_users": 300,      "session_duration": 1,      "custom_page_html": "<p>Include custom HTML here</p>",      "created_on": "2014-01-01T05:20:00.12345Z",      "modified_on": "2014-01-01T05:20:00.12345Z"    }  ]}

Preview the HTML code for a customized waiting room

Before making an API request to configure a waiting room web page with customized HTML, you can preview your custom HTML by uploading it to a preview endpoint:


In the request body, include the customized HTML content in the custom_html field:

{    "custom_html": "<p>Include custom HTML here</p>"}

Note that you pass HTML content to the preview endpoint in the custom_html field, but when you are using the API to configure a waiting room, you pass the HTML content in the custom_page_html field.

Example request:

curl -X POST "{zone-id}/waiting_rooms/preview"     -H "X-Auth-Email:"     -H "X-Auth-Key: xxxxxxxx"     -H "Content-Type: application/json"     --data '{"custom_html":"<p>Include custom HTML here</p>"}'

The preview endpoint returns a temporary URL in the response body where you can preview your custom page:

{  "result": {    "preview_url": ""  },  "success": true,  "errors": [],  "messages": []}

You do not have to have a Cloudflare account to access the preview link, so you can validate the waiting room webpage on multiple devices.

Preview the default or current waiting room web page

After generating a preview URL, use the following endpoint to generate a link to preview the currently configured web page for a waiting room, or the default page if no custom page is configured.


The link in the response displays the content of the custom_page_html field, rendered with mustache.

Use the optional force_queue query parameter to preview the waiting room web page when all traffic is force-queued.