--- title: Cloudflare Waiting Room description: Cloudflare Waiting Room allows you to route excess users of your website to a customized waiting room, helping preserve customer experience and protect origin servers from being overwhelmed with requests. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/index.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Cloudflare Waiting Room A virtual waiting room to manage peak traffic. Business and above Cloudflare Waiting Room allows you to route excess users of your website to a customized waiting room, helping preserve customer experience and protect origin servers from being overwhelmed with requests. --- ## Benefits Waiting Room protects your origin server by preventing surges in legitimate traffic that may overload your origin. Waiting Room also benefits your visitors by: * Keeping your application online and preventing them from reaching error pages. * Showing estimated wait times that are continuously updated. * Opening up new spots more quickly by tracking dynamic inflow and [outflow](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/#session-duration). * Remembering each visitor's status to prevent someone from losing their place in line or having to re-queue if they leave your site. * Appearing in your own [branding and style](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/), which enhances trust and lets you provide additional information as needed. --- ## Features ### Scheduled Event Customize the behavior of a waiting room for a specific period of time. [ Use Scheduled Event ](https://developers.cloudflare.com/waiting-room/additional-options/create-events/) ### Waiting Room Rules Create rules to indicate specific traffic or areas of your site or application that you do not want a waiting room to apply to. [ Use Waiting Room Rules ](https://developers.cloudflare.com/waiting-room/additional-options/waiting-room-rules/) ### Waiting Room Analytics Get insights into the traffic going through your waiting room. [ Use Waiting Room Analytics ](https://developers.cloudflare.com/waiting-room/waiting-room-analytics/) ### Additional hostname and path coverage Apply a single waiting room to multiple hostnames and paths within the same zone. [ Use Additional hostname and path coverage ](https://developers.cloudflare.com/waiting-room/how-to/place-waiting-room/) --- ## Related products **[Cloudflare for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/)** Cloudflare for SaaS allows you to extend the security and performance benefits of Cloudflare’s network to your customers via their own custom or vanity domains. **[Rules](https://developers.cloudflare.com/rules/)** Cloudflare Rules allows you to make adjustments to requests and responses, configure Cloudflare settings, and trigger specific actions for matching requests. **[SSL/TLS](https://developers.cloudflare.com/ssl/)** Cloudflare SSL/TLS encrypts your web traffic to prevent data theft and other tampering. --- ## Availability The following customers have access to Cloudflare Waiting Room: * Those qualified under [Project Fair Shot ↗](https://www.cloudflare.com/fair-shot/) * Customers on a Business or Enterprise plan Access to certain features depends on a customer's [plan type](https://developers.cloudflare.com/waiting-room/plans/). Note Enterprise customers can preview this product as a [non-contract service](https://developers.cloudflare.com/billing/preview-services/), which provides full access, free of metered usage fees, limits, and certain other restrictions. --- ## Prerequisites * [Cloudflare’s CDN](https://developers.cloudflare.com/cache/) is required to use the Waiting Room feature. * Configure a [proxied DNS record](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/) or a [proxied load balancer](https://developers.cloudflare.com/load-balancing/understand-basics/proxy-modes/) for the waiting room’s hostname. A DNS record is not auto-configured after a waiting room is created. * Visitors must enable cookies. Refer to [Waiting Room cookies](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/) for information on how cookies are used in Cloudflare Waiting Room. --- ## More resources [Pricing](https://www.cloudflare.com/plans/) Explore pricing options for Waiting Room. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}}]} ``` --- --- title: About description: Waiting Room queues visitors when your traffic approaches a previously defined threshold that might otherwise bring an application down. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/about.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # About Waiting Room queues visitors when your traffic approaches a previously defined threshold that might otherwise bring an application down. ![Waiting Room process flow showing how a request is managed by Cloudflare and placed in a waiting room before reaching the origin website](https://developers.cloudflare.com/_astro/waiting-room-process-flow.BQ9hOmEi_1dE16C.webp) ## User flow Once you have [created and activated a waiting room](https://developers.cloudflare.com/waiting-room/get-started/) for a specific application page: * If a page is not experiencing heavy traffic, a visitor accesses the page directly. * If page traffic approaches a [user-defined threshold](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/#session-duration), a visitor enters a virtual waiting room until it is their turn to access the page: * Each user receives a [cookie](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/) to manage the dynamic outflow of requests from the waiting room to the origin website in [First In First Out (FIFO)](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/#first-in-first-out-fifo) order. * While in the waiting room, the user's browser automatically refreshes every 20 seconds to give them updated information about their estimated wait time. * When a user exits the waiting room and reaches your application, they can leave and re-enter without waiting for the length of time specified by the [session duration](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/#session-duration). * Because waiting rooms support dynamic inflow and [outflow](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/#session-duration), new spots appear more quickly and estimated wait times are lower and more accurate. ## Architecture Waiting Room is built on [Workers](https://developers.cloudflare.com/workers/) that runs across a global network of Cloudflare data centers. When a request comes to a host or path covered by a Waiting Room, that request goes to a Waiting Room Worker in the closest geographic data center. The Worker then needs to make a decision: whether to send users to the queue or the website. That decision itself depends on two factors: [admin-defined thresholds](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/) and the Waiting Room state. For admin-defined thresholds, the two measures that matter are `total active users` and `new users per minute`: * `total active users` is a target threshold for how many simultaneous users you want to allow on the pages covered by your waiting room. * `new users per minute` defines the target threshold for the maximum rate of user influx to your website per minute. A sharp spike in either of these values might result in queuing. Another configuration that affects how we calculate `the total active users` is `session duration`. A user is considered active for `session duration` minutes since the request is made to any page covered by a waiting room. The other factor is the Waiting Room state, which is maintained at the local data center level but then also changes continuously based on the traffic around the world. Each data center works with its own Waiting Room state. This state is a snapshot of the traffic pattern for the website around the world available at that point in time. The advantage of using this approach - making decisions at the Worker level - is that we can make decisions without any significant latency added to the request. The algorithm for Waiting Room dynamically allocates a certain number of slots available to each Worker based on the Waiting Room state. Queueing starts when the slots run out within the Worker. The lack of additional latency added enables the customers to turn on the waiting room all the time without worrying about extra latency to their users. The Waiting Room state is updated with global information every few seconds. We have a pipeline set up in Cloudflare [Durable Objects](https://developers.cloudflare.com/durable-objects/) that ensures changes in traffic get propagated around the world. This architecture ensures that we do not introduce additional latency, as well as that we are making decisions with as near-time accuracy as possible. For even more details about the architecture and why we made these decisions, refer to our [deep-dive technical blog ↗](https://blog.cloudflare.com/how-waiting-room-queues). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/about/","name":"About"}}]} ``` --- --- title: Get started description: Before you start this tutorial, make sure you have: image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/get-started.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Get started --- ## Before you begin Before you start this tutorial, make sure you have: * Reviewed the [About](https://developers.cloudflare.com/waiting-room/about/) Waiting Room page.). * Reviewed your [rate limiting rules](https://developers.cloudflare.com/waf/rate-limiting-rules/) to make sure they allow at least one request every 20 seconds (required for automatic page refreshes). --- ## Step 1 — Plan out your waiting room Before you create your waiting room, think about how you want it to appear and operate. ### Location Which page will you cover with a waiting room? You can only have one waiting room per page, so you need to identify the high-traffic areas of your website. Specify the URL for your page by setting the `hostname` and `path` in your [configuration settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/). Advanced Waiting Room customers can also [specify multiple hostname and path combinations](https://developers.cloudflare.com/waiting-room/how-to/place-waiting-room/) for the same zone. ### Access method You can direct visitors to your high-traffic page: * Directly (via URL) * Indirectly (via [a redirect](https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/)) ### Queue activation When you [activate your waiting room](#step-3--activate-your-waiting-room), choose whether: * [**All visitors**](#queue-all-visitors) to be queued, in preparation for a product release or other time-based event. * Only [**some visitors**](#queue-some-visitors) to be queued, as traffic reaches the thresholds defined in `Total active users` and `New users per minute`. ## Step 2 — Create your waiting room Create your waiting room by: * Using the [dashboard](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/). * Using the [API](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/). ### Appearance (optional) Some customers can [customize the design](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/) of their waiting room by editing the page's HTML and CSS. If you have this ability, think about how you want the page to appear. ### Prepare your waiting room for mobile application traffic If you need to manage traffic in a non-browser environment such as a mobile app or web app, use a [JSON-friendly waiting room](https://developers.cloudflare.com/waiting-room/how-to/json-response/) that can be consumed via your API endpoints. Note that if you have a mobile app or web app that depends on resources that would be protected by a waiting room, you will need to update those clients to handle Waiting Room appropriately. ## Step 3 — Activate your waiting room Depending on your [queue activation](#queue-activation), you may deploy your waiting room differently. ### Queue some visitors To queue visitors only when necessary: 1. Go to **Traffic** \> **Waiting Room**. 2. On a waiting room, set **Enabled** to **On**. 3. Your waiting room will begin queueing visitors once it approaches the target traffic thresholds defined in [**Total active users**](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/) and in [**New users per minute**](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/). ### Queue all visitors To queue all visitors prior to a time-based offering, set up a pre-queue as part of a [waiting room event](https://developers.cloudflare.com/waiting-room/additional-options/create-events/#create-an-event-from-the-dashboard). To start queueing all new visitors without a scheduled event: 1. Go to **Traffic** \> **Waiting Room**. 2. On a waiting room: 1. Ensure **Enabled** is set to **On**. 2. Set **Queue-all** to **On**. 3. Your waiting room will begin queueing all new visitors and will not allow any new visitors to the path protected by your waiting room. Queue-all will override all other waiting room settings, including event settings. Note Only new visitors will be queued. Active users that are already on your website will continue there and will not return to the queue until their session expires. 1. To begin allowing visitors to the path protected by your waiting room, set **Queue-all** to **Off**. ## Step 4 — Next steps After you have created and deployed your first waiting room, you might also want to: * [Test your waiting room](https://developers.cloudflare.com/waiting-room/additional-options/test-waiting-room/) before it goes live. * [Monitor your traffic](https://developers.cloudflare.com/waiting-room/how-to/monitor-waiting-room/) in real time. * [Troubleshoot](https://developers.cloudflare.com/waiting-room/troubleshooting/) potential issues. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/get-started/","name":"Get started"}}]} ``` --- --- title: Plans description: The features available for a waiting room depend on your plan type. You can only have one plan per zone. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/plans.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Plans The features available for a waiting room depend on your plan type. You can only have **one plan** per zone. One basic waiting room is included in all Business and Enterprise plans. On an Enterprise plan, you can purchase advanced waiting room(s) to unlock all of the additional advanced features. | Free | Pro | Business | Enterprise | | | -------------------------------------- | --- | -------- | ------------------------- | ------------------------------------------------------------------------------------- | | Availability | No | No | Yes | Yes | | Number of rooms | 0 | 0 | 1 | 1 (default) _With advanced:_Custom (can purchase more) | | Customized templates | No | No | No | Advanced add-on | | Queueing methods | No | No | First In First Out (FIFO) | First In First Out (FIFO) (default) _With advanced:_FIFO, Random, Reject, Passthrough | | Configure multiple hostnames and paths | No | No | No | Advanced add-on | | Disable session renewal | No | No | No | Advanced add-on | | JSON-friendly response | No | No | No | Advanced add-on | | Customize queuing status code | No | No | Yes | Yes | | Scheduled events | No | No | No | Advanced add-on | | Waiting Room rules | No | No | No | Advanced add-on | | Session Revocation | No | No | No | Advanced add-on | | SEO Crawler Bypassing | No | No | Yes | Yes | | Turnstile Widget Mode | No | No | Invisible only | Invisible (default) _With advanced:_Invisible, Managed, Non Interactive | | Turnstile Fail Action | No | No | Log only | Log only (default) _With advanced:_Log only & Infinite queue | Note Enterprise customers can preview this product as a [non-contract service](https://developers.cloudflare.com/billing/preview-services/), which provides full access, free of metered usage fees, limits, and certain other restrictions. ## How do I get started? To get started with Waiting Room, review our [setup guide](https://developers.cloudflare.com/waiting-room/get-started/). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/plans/","name":"Plans"}}]} ``` --- --- title: Waiting Room Analytics description: Waiting Room Analytics gives you historical insights into the traffic going through your waiting room compared to your waiting room settings. Data is stored for the past 30 days. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/waiting-room-analytics.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Waiting Room Analytics Waiting Room Analytics gives you historical insights into the traffic going through your waiting room compared to your waiting room settings. Data is stored for the past 30 days. Using Waiting Room Analytics, you can: * Evaluate peak traffic flow through your waiting room and onto your site. * Determine how long users spent in the waiting room. * Use analytics to help calibrate your waiting room settings. ## ​Dashboard Analytics To access your waiting room’s analytics in the dashboard: 1. In the Cloudflare dashboard, go to the **Waiting Room** page. [ Go to **Waiting Room** ](https://dash.cloudflare.com/?to=/:account/:zone/traffic/waiting-rooms) 2. Expand the waiting room you would like to review metrics for, to display a preview of your waiting room analytics. The preview gives you insights into peak traffic through your waiting room over the last 24 hours including: Maximum active users, Maximum queued users and Typical time in queue for queued users. 3. Select **View More** under the Waiting Room Analytics section to get more historical analytics for your waiting room. 4. The time range for all of the metrics displayed defaults to the last 24 hours. To change the time range, select from the drop down. You can select any time range from the last 30 days that is a minimum of 30 minutes. ## Event Analytics If your waiting room has a completed scheduled event, you can quickly access the event’s analytics by expanding the row for the waiting room you are interested in and selecting the event time. The link opens the analytics view for that waiting room, including information from the pre-queueing period to the end of the event. To save this event information, you can either select **Download data** or **Print report**. If you delete the event, the time period link will no longer appear in your dashboard. If you edit the timing of the event, the time period link will update as well. If you do not get a link to your event’s analytics, one of the following may have happened: * Your event has not happened yet. * Your event started more than 30 days ago. ## Metrics These are metrics available in the Analytics dashboard and how they are calculated. ### Time in queue Time in queue summary values give you an insight into the user experience by indicating how long queued users spent waiting to enter your application. It displays the time waited for the typical user, as well as for those who waited the longest, for the time period you have selected. These values are an indicator of the impact your waiting room settings combined with the traffic to your waiting room had on wait times. If wait times are higher than you would like, and you feel comfortable doing so, you could consider taking any or all of the following actions: * Increase `total_active_users` configured value. * Increase `new_users_per_minute` configured value. * Decrease `session_duration`. * Disable session renewal. Note Note that wait times are only calculated for users who went from the waiting room to your origin. ### Time on origin Time on origin summary values estimate how long users spent on the pages covered by your waiting room before leaving. For the time period selected, you will have access to the estimated time spent on origin for the typical user, as well as the time on origin for those who spend the most time on your site. Keep in mind that if your session renewal is disabled and there is no active queueing, users are issued a new waiting room session every `session_duration` minutes. Therefore, these users may be staying for multiple sessions. The time on origin for these users restarts each time a session expires. The following are some takeaways you could have depending on the time on origin values. You may want to increase session duration, giving users more time to make subrequests, and/or enable session renewal if: * You have session renewal disabled. * You have frequent, active queueing with long wait times. * The typical time on origin is around 70% of your configured session duration. These may be indicators that users need more time to complete their desired tasks on your site. You may want to decrease session duration and/or disable session renewal if: * Your top 5% time on origin is less than 70% of your configured session duration. * You are seeing high queue times and do not want to increase traffic limits. These may be indicators that users do not need as much time on your site and are taking up spots on your origin. ### Active users vs. queued users The Active users chart is a time series chart that displays the maximum active users on any URLs covered by your waiting room as well as maximum queued users. These values are shown compared to your configured active user target threshold. A new user is a novel request made to any URLs covered by the waiting room. Waiting Room counts the request as new if no waiting room cookie is tied to the request. Once the request is made, a waiting room cookie is issued. If there is an active queue, the user will be considered a queued user. Once that user makes it through the queue and onto the site, they are now an active user and remain active as long as they keep making HTTP requests to waiting room URLs at least once every `session_duration` minutes. To identify and hone in on peak traffic, select a longer time period, such as 30 days. Then, drag your cursor to the left and right of any time period you would like to check with more granularity to zoom in. You can zoom in until each bar represents a one minute interval. All other metrics on the page will update automatically to reflect the data behind the time period selected. To check for more details about a particular moment in time, hover over a bar on the graph. This displays a tooltip which will indicate the following for the time period that bar represents: * Maximum active users reached * Maximum queued users reached * Configured active user target values Queueing may occur below your configured limits, and active users may sometimes exceed your configured limits. Refer to the [Queuing activation](https://developers.cloudflare.com/waiting-room/how-to/monitor-waiting-room/#queueing-activation) section for more information. ### New users per minute The New users per minute chart shows how many new users per minute passed through the waiting room to your origin compared to your configured New users per minute target threshold. Like the Active users chart, you can zoom in by highlighting to the left and right of the time period you are interested in, which will update the other chart as well as summary values. As you zoom out, each data point is averaged. Therefore, as you zoom in, values may fluctuate. ### Turnstile Widget Traffic The Turnstile widget traffic chart shows the number of challenges issued per minute and the distribution of traffic seen with these challenges. Traffic is categorized into three main categories: * Likely Human - This represents the number of challenges that were successfully solved. * Likely Bots - This represents the number of unsolved challenges. * Bots - This represents the number of failed challenges. If your waiting room has the infinite queue option enabled, you will see a line on the graph representing the number of refresh requests from bots in the infinite queue. ## ​​GraphQL Analytics You can query your Waiting Room analytics data via GraphQL API. Waiting Room analytics provides near real-time visibility into your Waiting Room, allowing you to visualize the traffic to your application and how it is managed respecting the configured limits. Here are some query examples to get started: Fetch values for total active users and new users per minute over a certain period. This is a simple query to fetch metrics values. You can filter the data with the zone tag and query the `waitingRoomAnalyticsAdaptive` dataset. In this example, we have applied this query only on two metrics, but you can explore the schema and fetch the raw values from the GraphQL dataset without applying any aggregation methods. Request ``` { viewer { zones(filter: {zoneTag: "example-zone"}) { waitingRoomAnalyticsAdaptive(limit: 3, filter: {datetime_gt: "2023-03-05T19:14:30Z", datetime_lt: "2023-03-07T19:13:00Z", waitingRoomId: "example-waiting-room-id"}) { totalActiveUsers newUsersPerMinutes } } } ``` Response ``` { "data": { "viewer": { "zones": [ { "waitingRoomAnalyticsAdaptive": [ { "newUsersPerMinute": 77, "totalActiveUsers": 1023 }, { "newUsersPerMinute": 113, "totalActiveUsers": 1009 }, { "newUsersPerMinute": 99, "totalActiveUsers": 927 } ] } ] } }, "errors": null } ``` Find the average of total active users and new users per minute over a certain period, and aggregate this data over a period of 15 minutes. This query calculates the average of total active users and new users per minute. The time dimension in the query is 15 minutes, therefore the data is aggregated over 15 minutes for the selected time period. Request ``` { viewer { zones(filter: {zoneTag: "example-zone"}) { waitingRoomAnalyticsAdaptiveGroups(limit: 10, filter: {datetime_geq: "2023-03-15T04:00:00Z", datetime_leq: "2023-03-15T04:45:00Z", waitingRoomId: "example-waiting-room-id"}, orderBy: [datetimeFifteenMinutes_ASC]) { avg { totalActiveUsers newUsersPerMinute } dimensions { datetimeFifteenMinutes } } ``` Response ``` { "data": { "viewer": { "zones": [ { "waitingRoomAnalyticsAdaptiveGroups": [ { "avg": { "newUsersPerMinute": 119, "totalActiveUsers": 1180 }, "dimensions": { "datetimeFifteenMinutes": "2023-03-15T04:00:00Z" } }, { "avg": { "newUsersPerMinute": 146, "totalActiveUsers": 961 }, "dimensions": { "datetimeFifteenMinutes": "2023-03-15T04:15:00Z" } }, { "avg": { "newUsersPerMinute": 144, "totalActiveUsers": 1015 }, "dimensions": { "datetimeFifteenMinutes": "2023-03-15T04:30:00Z" } } ] } ] } }, "errors": null } ``` Find the weighted averages of time on origin (50th percentile) and total time waited (90th percentile) for a certain period and aggregate this data over one hour. This query calculates the weighted averages of the metrics for a certain period of time aggregated hourly. Request ``` { viewer { zones(filter: {zoneTag: "example-zone"}) { waitingRoomAnalyticsAdaptiveGroups(limit: 10, filter: {datetime_geq: "2023-03-15T04:00:00Z", datetime_leq: "2023-03-15T04:45:00Z", waitingRoomId: "example-waiting-room-id"}, orderBy: [datetimeHour_ASC]) { avgWeighted { timeOnOriginP50 totalTimeWaitedP90 } dimensions { datetimeHour } } ``` Response ``` { "data": { "viewer": { "zones": [ { "waitingRoomAnalyticsAdaptiveGroups": [ { "avgWeighted": { "timeOnOriginP50": 99.19, "totalTimeWaitedP90": 1625.63 }, "dimensions": { "datetimeHour": "2023-03-15T04:00:00Z" } } ] } ] } }, "errors": null } ``` ## Why is there no data for my waiting room? If you are not seeing any historical data for your waiting room, one or more of the following may be true: * Your waiting room was not receiving any traffic for the time period you are inspecting. * Your waiting room was not enabled for the time period you are inspecting. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/waiting-room-analytics/","name":"Waiting Room Analytics"}}]} ``` --- --- title: API reference image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/api-reference.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # API reference ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/api-reference/","name":"API reference"}}]} ``` --- --- title: FAQ description: Below you will find answers to our most commonly asked questions about the Waiting Room. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/troubleshooting.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # FAQ Below you will find answers to our most commonly asked questions about the Waiting Room. * [Configuration](#configuration) * [Features and products](#features-and-products) * [User behavior](#user-behavior) * [Monitor your waiting room](#monitor-your-waiting-room) --- ## Configuration ### Can I display my waiting room page in another language? Yes. For more details, refer to [Customize a waiting room](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/). ### Why does my waiting room look different than how I designed it? If you have [customized your waiting room template](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room): 1. Preview your template before deploying it to production. 2. If you encounter any issues, check for proper syntax and a closing backslash (/). Note Only Enterprise customers can customize the appearance of their waiting room. ### What can I update when my waiting room is actively queueing? You can update a [waiting room's template](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room) and those changes will be visible to users in near-real time. We recommend these updates as a way to engage with users and provide updated information or expectations. You can also update the [configuration settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings) of a waiting room, but only make these changes when necessary. These changes may impact the estimated wait time shown to end users and cause unnecessary confusion. ## Features and products ### Which features are included in my Waiting Room plan? To check which features are available to different plan types, refer to [Plans](https://developers.cloudflare.com/waiting-room/plans/). ### How does Waiting Room interact with other Cloudflare products? Some Cloudflare products run before a waiting room acts on traffic: * DDoS Mitigation * Web Application Firewall (WAF) * Bot Management * Page Rules Other Cloudflare products run after a waiting room acts on traffic: * Workers ## User behavior ### What happens if a user refreshes their tab when in a waiting room? A manual tab refresh has no effect on a user's position in your waiting room. However, if they close their tab and then try to access the application again during active queueing, they will lose their spot and have to go to the back of the queue. ### What happens if a queued user leaves the queue? When a user joins the queue, they are placed into a bucket which is their general position in line. When a user leaves the queue (closes the browser or tab), their place in line is held for five minutes after the last refresh. This grace period allows users to keep their position in line if they experience a brief disconnection. After five minutes, the grace period expires and they are no longer counted as waiting in the queue. ## Monitor your waiting room ### Why do I observe a few users being queued in the dashboard? Some users might be queued before your waiting room reaches is limit due to architectural designs. For more details on the behavior and how to fix it, refer to [​​Queueing activation](https://developers.cloudflare.com/waiting-room/how-to/monitor-waiting-room#queueing-activation). ### Why are some users not being queued in my waiting room? If you notice users not being queued to your waiting room, make sure the path you defined exactly matches the path of your website. The path is case-sensitive, so if you have a waiting room set up for `/Black-Friday-Sale` and users go to `/black-friday-sale`, they will bypass your waiting room. For more details, refer to [Best practices](https://developers.cloudflare.com/waiting-room/reference/best-practices). ### Why are users being blocked from entering my waiting room? If you have Rate Limiting, check your [rate limiting rules](https://developers.cloudflare.com/waf/rate-limiting-rules/). The Waiting Room queue page refreshes every 20 seconds by populating the refresh header. If you have a rule set to block requests from a specific IP within 20 seconds, the user in the waiting room will be blocked. Make sure your rules allow at least one request every 20 seconds. Your user also might not have [cookies](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie) enabled. If they do not enable cookies and your waiting room is actively queueing traffic, they will not reach your endpoint until the queueing stops. ### Why is the estimated wait time increasing for some users? Estimated wait times may increase if the rate of users leaving your site decreases. The estimated wait time is updated upon each page refresh based on the most recently available information about the rate of slots opening up on your site and the number of users ahead of the user in line. To make this increase less likely, you could limit the amount of time users are allowed to spend on your site by disabling session renewal. Be aware that, if you change your traffic settings, estimated wait times will change as well. ### Why is `new users per minute` low when there is capacity available? The `new users per minute` metric tracks how many users were accepted to the origin in the last minute. It is only incremented when a queued user refreshes and is accepted to the origin. If the waiting room queueing method is set to `fifo`, we will wait until all queued users in a minute-based bucket are accepted before moving to the next bucket. If many of the users in a bucket have abandoned the queue, then the waiting room must wait until their place in line expires before moving on to the next bucket. This can cause `new users per minute` to be low when only a small percentage of queued users are actually still waiting. This is often noticed if there is a large amount of automated traffic which does not handle cookies properly. Since bots usually do not persist cookies from one request to the next, they end up counting as multiple inactive users in the queue and prevent full utilization of available slots. For this reason, we recommend leveraging [Bots Management](https://developers.cloudflare.com/bots/) products to keep bots out of the queue. Waiting Room Advanced customers can try our [Turnstile](https://developers.cloudflare.com/turnstile/) integration, which prevents bots from clogging the line by putting them in an infinite queue. ### Why are my Waiting Room analytics and Google analytics not matching? Waiting Room relies on a session cookie to count and keep track of active users. The duration for which a user is considered active depends on the waiting room configuration. The key setting involved in this calculation is [session duration](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/#session-duration). By default, Waiting Room considers a user active from the time of their last request made with a session cookie, until the configured session duration elapses. Customers with an advanced Waiting Room setup can modify this behavior by [disabling session renewal](https://developers.cloudflare.com/waiting-room/how-to/control-user-session/#disable-session-renewal-to-limit-browsing-time) and/or explicitly [revoking sessions](https://developers.cloudflare.com/waiting-room/how-to/control-user-session/#revoke-a-users-session-using-origin-commands) using an origin command. If the session duration is set to a higher value, a user who makes only a single request will be considered active for longer than they actually were. This can cause the `Total Active Users` metric to appear higher than the active users metric reported by Google Analytics for the same time period, as Google Analytics only counts users who made requests during that specific period. For example, if the session duration is set to 30 minutes and you look at the last 10 minutes of active users in Google Analytics, the number of active users reported by Waiting Room will be higher, since it includes users from the last 30 minutes. Another key difference is that Waiting Room runs on requests made to the origin, while Google Analytics requires a user-agent to run JavaScript (via Google Tag). Waiting Room creates new sessions and tracks user metrics based on the HTTP request path, without requiring any additional JavaScript execution by a user-agent. In contrast, Google Analytics requires user-agents to execute JavaScript and make a secondary request to report details to Google Analytics. If a large portion of the traffic is automated, it may not be captured by Google Analytics. However, Waiting Room analytics will count such traffic as new users and consider them active for the configured session duration. ### Why did my traffic exceed the New Users Per Minute threshold? Waiting Room is a distributed system, and achieving perfect global counting in real time is challenging due to the time required for state propagation across data centers worldwide. The budgeting logic is structured around both data center-specific and global budgets. Data center budgets are allocated based on the historical traffic received by each data center, while global budgets (a portion of the total available budget) are maintained to allow new users to enter from any data center globally. In the case of a rapid spike — rising to several thousand users within a minute — the global state propagation process takes approximately two minutes, resulting in a delay before all data centers become aware of the spike. If this information is not disseminated quickly enough to other locations, temporary overshooting may occur, particularly when lower limits are in place. This occurs because the portion of the budget reserved for new users to enter a data center is equally available to all data centers. Until the usage of this budget is synchronized across all data centers, each data center may consume a portion that collectively exceeds 100% of the global budget allocated for new users. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/troubleshooting/","name":"FAQ"}}]} ``` --- --- title: Create scheduled events description: When you want to customize the behavior of a waiting room for a specific period of time — such as changing the queueing method or increasing the total active users — set up a scheduled event. You can do this from the dashboard or via the API. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/additional-options/create-events.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Create scheduled events When you want to customize the behavior of a waiting room for a specific period of time — such as changing the queueing method or increasing the total active users — set up a **scheduled event**. You can do this from the dashboard or via the API. Any properties set on the event will override the default property on the waiting room for the duration of the event. Note Only some customers can support scheduled events with their waiting rooms. For more details, refer to our [Plans](https://developers.cloudflare.com/waiting-room/plans/) page. ## Create an event from the dashboard 1. Within your application, go to **Traffic** \> **Waiting Room**. 2. Expand a waiting room and select **Schedule event**. 3. Customize the details for your event: name the event, add a description (optional), and select a Start Date Time and an End Date Time. 4. You can also enable the pre-queueing — in this case you need to define a pre-queueing time. And you can also select **Shuffle at event start** and all users in the pre-queue will be randomly admitted at event start. Note Enabling pre-queuing will send all new users to your pre-queue during the pre-queueing time period. If you would like to also pre-queue users already active, make the pre-queueing time period longer than the session duration and disable session renewal in the **Settings** section. Once active users sessions expire, they will be placed into the pre-queue before your event starts. 5. Select **Next**. 6. In the **Settings** section, you can define new values for your Total active users, New users per minute, Session duration, Session Renewal, and Queueing Method. For each of these settings you also have the option to always inherit the values defined in your waiting room. With this option, if you change the settings of your base waiting room, the corresponding Event setting will update as well. Note If you choose to override the values of Total active users, you must also override the number of New users per minute, and vice versa. 7. Select **Next**. 8. In the customization section, you can select Always inherit your waiting room’s template (default) or you can override it with a Custom Event Template. In this case, you need to import your own template. Make sure to preview the result before continuing. 9. Select **Next** and review your Event details and settings. 10. Select **Save**. Note The waiting room must be set to enabled for the event to activate. If your event is set to enabled but your waiting room is not, the event will not activate. In your waiting room page, in the **Next Event** column you can visualize the date of the next event scheduled. This columns will read `N/A` in case there is no event scheduled for that waiting room. You can always suspend, edit or delete your event. Note You have a limit of five events per waiting room. To create a new event after you have reached this limit, you can delete a previous event. ## Create an event via API To create an event, make a [POST request](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/events/methods/create/) including [required and optional parameters](#parameters). Any properties set on the event will override the default property on the waiting room for the duration of the event. If you are using a [custom template](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/#custom-waiting-room), you may want to add [relevant variables](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/update/) to your template (listed under the `json_response_enabled` parameter). Note If you need to create overlapping events, use different waiting rooms. ### Parameters Though most parameters are identical to those in a regular waiting room, there are a few unique to creating an event. For a complete list of event settings, please refer to [Create an Event](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/events/methods/create/). * `name` (required): Unique name with alphanumeric characters, hyphens, and underscores. * `event_start_time` (required): ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. Must occur at least 1 minute before `event_end_time`. * `event_end_time` (required): ISO 8601 timestamp that marks the end of the event. * `shuffle_at_event_start`: If **true** and `prequeue_start_time` is not null, users in the prequeue will be shuffled randomly at the `event_start_time`. Commonly used to ensure fairness if your event is using a [**FIFO** queueing method](#set-up-a-lottery). * `prequeue_start_time`: ISO 8601 timestamp that marks when to begin queueing all users before the event starts. Must occur at least **5 minutes before** `event_start_time`. * `description`: A text description providing more detail about the event. * `suspended`: If **true**, the event is ignored and traffic is handled based on the waiting room's typical configuration. ### Queueing methods When setting up events, you may want to also adjust the default queueing methods for your waiting room. Set the waiting room's queueing method to [**Passthrough**](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/#passthrough) when you want to allow traffic normally, but then restrict traffic during a scheduled event. Set the waiting room's queueing method to [**Reject**](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/#reject) when you want to block all traffic normally, but then allow traffic during special events like signups or ticket sales. ## Set up a "lottery" Set up a "lottery" system to reward all users who enter into the queue prior to your event start time. Users who reach your application **during the prequeue period** are [randomly assigned](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/#random) a place in line when the event starts. If the event uses [FIFO ordering](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/#first-in-first-out-fifo), users who reach your application **after the prequeue period** are assigned places after users from the prequeue. To set up a "lottery", include the [following parameters](#parameters) in your API request: * `prequeue_start_time` * `shuffle_at_event_start` ## Preview an event configuration Since some properties set on an event will override the default property of a waiting room for the duration of an event, you should use the API to [preview an event configuration](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/events/subresources/details/methods/get/) before it begins. This command shows you the event's configuration as if it were active, meaning that inherited fields from the waiting room will display their current values. ## Edit an event To edit an event, use a [PATCH request](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/events/methods/edit/). ## Disable events You can disable an event by setting its `suspended` parameter to `true`. Additionally, events will not become active if a waiting room itself is **Disabled**. ## Schedule a maintenance page Follow these steps if you would like to deploy a scheduled maintenance page, with no queueing before or after the maintenance window. 1. [Create a waiting room](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/) with [Passthrough](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/#passthrough) queueing method enabled. 2. Create a waiting room event for this room with [Reject](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/#reject) queueing method enabled. After the scheduled event has ended, users will have access to your site. You can end the maintenance window before the scheduled event is over by setting the event to disabled. ## Other API commands | Function | Command | | -------------------------------------------------------------------------------------------------------------------------- | ------- | | [Get event details](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/events/methods/get/) | GET | | [List scheduled events](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/events/methods/list/) | GET | | [Delete event](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/events/methods/delete/) | DELETE | ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/additional-options/","name":"Additional options"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/additional-options/create-events/","name":"Create scheduled events"}}]} ``` --- --- title: Embed in an iFrame description: Because of how a waiting room tracks visitor progress, you need to specify certain cookie attributes to properly embed a waiting room in an iFrame. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/additional-options/embed-waiting-room-in-iframe.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Embed in an iFrame Because of how a waiting room [tracks visitor progress](#background), you need to [specify certain cookie attributes](#allow-cookies-to-pass-through-iframes) to properly embed a waiting room in an iFrame. ## Background The [SameSite attribute of a cookie ↗](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) specifies whether that cookie can be shared with other domains that load on the same page (ad banners, iFrames). By default, browsers do not send cookies on cross-site subrequests to prevent attackers from stealing or manipulating information present in your cookies. However, this behavior can prevent a waiting room from queueing a user properly if that waiting room is embedded in an iFrame. The waiting room depends on the [\_\_cfwaitingroom cookie](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/) to track a user in the queue. But, since the browser blocks the cookie from reaching the waiting room by default, an active and queueing waiting room cannot queue the user and will never let them access the application. ## Available options To customize how your waiting room responds to cookies, include the `cookie_attributes` object when you [create a waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/) (only available via the API). Available options include: * `samesite`: Configures the `SameSite` attribute on the waiting room cookie: * **auto** (default): Meant to be as flexible as possible, defaulting to **lax** but becoming **none** if you have enabled [**Always Use HTTPS**](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/). * **lax**: Cookies are not sent on typical cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site * **strict**: Cookies will only be sent in a first-party context. * **none**: Cookies will always be sent. * `secure`: Configures the `Secure` attribute on the waiting room cookie, which requires the request to be made over `https`: * **auto** (default): Meant to be as flexible as possible, defaulting to **never** but becoming **always** if you have enabled [**Always Use HTTPS**](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/). * **always**: Cookies can only be sent using `https` requests. * **never**: Cookies can be sent using `http` or `https` requests. ## Allow cookies to pass through iFrames If you are embedding a waiting room in an iFrame, specify the following values on `cookie_attributes` object when [creating a waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/) (only available via the API): * `samesite`: `none` * `secure`: If you have [**Always Use HTTPS**](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/) enabled, set to `auto`. If you have it disabled, set to `always`. ### Example Request Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Write` Create waiting room ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "shop_waiting_room", "description": "Waiting room for webshop", "host": "shop.example.com", "path": "/shop", "queue_all": true, "new_users_per_minute": 200, "total_active_users": 300, "session_duration": 1, "disable_session_renewal": false, "json_response_enabled": false, "queueing_method": "FIFO", "cookie_attributes": { "samesite": "none", "secure": "auto" } }' ``` Response ``` { "success": true, "errors": [], "messages": [], "result": [ { "id": "1111111111111111111111", "created_on": "2021-01-01T05:20:00.12345Z", "modified_on": "2021-01-01T05:20:00.12345Z", "name": "shop_waiting_room", "description": "Waiting room for webshop", "host": "shop.example.com", "path": "/shop", "queue_all": true, "new_users_per_minute": 200, "total_active_users": 300, "session_duration": 1, "disable_session_renewal": false, "json_response_enabled": false, "queueing_method": "FIFO", "cookie_attributes": { "samesite": "none", "secure": "auto" } } ] } ``` ## Limitations Major web browsers have introduced restrictions on third-party cookies, which happen to be the same type of cookies used by waiting rooms within iframes. Waiting Room uses [Cookies Having Independent Partitioned State (CHIPS) ↗](https://developer.mozilla.org/en-US/docs/Web/Privacy/Privacy%5Fsandbox/Partitioned%5Fcookies) to work around these restrictions, but there are some drawbacks: * A user viewing the waiting room both within an iframe and outside the iframe will be treated as two separate users, with each instance potentially exiting the queue at different times and counting separately in analytics. * For a waiting room to be embedded in an iframe, both the embedded page and the embedding page must be accessed over HTTPS. * CHIPS is not supported on Safari or Safari-derived browsers, like Orion and most iOS browsers, unless they have third-party cookie blocking disabled in their settings. These users will be stuck at the end of the queue, unable to progress until the queue is empty, and may count multiple times in analytics. In general, if there is an issue setting and retrieving the waiting room cookie, you should expect users to be stuck at the end of the queue, and counting as multiple users in analytics. These limitations may not apply if the embedded page and embedding page share a common domain name. For example, a page at `example.com` embedding a waiting room at `shop.example.com` may be considered first party by browsers, and not subject to third-party cookie restrictions. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/additional-options/","name":"Additional options"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/additional-options/embed-waiting-room-in-iframe/","name":"Embed in an iFrame"}}]} ``` --- --- title: Combine with Cloudflare for SaaS description: If your application is using a custom hostname — meaning your SaaS provider is using Cloudflare for SaaS — your application can support a waiting room. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/additional-options/ssl-for-saas.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Combine with Cloudflare for SaaS If your application is using a custom hostname — meaning your SaaS provider is using [Cloudflare for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/) — your application can support a waiting room. ## Applications on Cloudflare If your application is already using Cloudflare, create a waiting room using the [typical process](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/). ## Applications not on Cloudflare If your application is not using Cloudflare, you need to ask your SaaS provider to configure a waiting room on [your Cloudflare for SaaS zone](https://developers.cloudflare.com/waiting-room/how-to/place-waiting-room/#custom-hostnames). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/additional-options/","name":"Additional options"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/additional-options/ssl-for-saas/","name":"Combine with Cloudflare for SaaS"}}]} ``` --- --- title: Test a waiting room description: Follow this tutorial to test your waiting room behavior in response to load. To accurately simulate traffic, run your test script or planner for a period of time longer than a minute, ideally more than 2-3 minutes. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/additional-options/test-waiting-room.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Test a waiting room Follow this tutorial to test your waiting room behavior in response to load. To accurately simulate traffic through your waiting room with a load test, run your test script or planner for a period of time longer than a minute, ideally more than 2-3 minutes. You can run a load test using a variety of tools including [loader.io ↗](http://loader.io), [jmeter ↗](http://jmeter.apache.org), and [postman.com ↗](http://postman.com). You can also write a plain shell script to simulate user requests (each representing a distinct user). Warning This tutorial uses an open-sourced load testing tool that is not created or supported by Cloudflare. --- ## Before you begin Before you start this tutorial, ensure you have: * Reviewed the [About](https://developers.cloudflare.com/waiting-room/about/) Waiting Room page. * For this tutorial, we will use an open source tool from Apache, [JMeter ↗](https://jmeter.apache.org/). You can download the binary from [JMeter's website ↗](https://jmeter.apache.org/download%5Fjmeter.cgi). --- ## 1\. Download sample script First, download the [sample ↗](https://github.com/yj7o5/cf-waiting-room-testing/blob/main/plan.jmx) JMeter plan (configuration file) from GitHub. This sample plan simulates 200 active users visiting the site, slowly ramping up traffic within the first minute and then maintaining 200 active users for the next three minutes. The test plan for this tutorial follows the setup outlined in the next steps. ## 2\. Edit and run the sample plan Before running the sample plan, edit the waiting room in the test plan to point to your own waiting room. 1. Select **Waiting Room Simulation** to expand the test plan and then select **Request origin with waiting room** to update the test configuration. ![Select Request origin with waiting room in the Waiting Room Simulation panel](https://developers.cloudflare.com/_astro/simulation-panel.BOynNfQl_20776m.webp) 1. In the **HTTP Request** section update the **Protocol**, **Server Name or IP**, and **Path** fields to point to your test URL with waiting room enabled. For example, if your full URL looks like `https://www.example.com/deals/summer`, then the fields should match as the following: | Field | Value | | ----------------- | ------------------------------------------- | | Protocol | https | | Server Name or IP | [www.example.com ↗](http://www.example.com) | | Path | deals/summer | ![Update the HTTP Request section](https://developers.cloudflare.com/_astro/http-request-section.DlSKTrFb_Z4WyLu.webp) Then, select the **play** button to get the test started. This should take roughly around 3-4 minutes. ![Select the play button](https://developers.cloudflare.com/_astro/navigation.CqQsxXoC_Z1zxoei.webp) * Each simulated user has the following attributes: * Contains a Cookie jar for cookies persistence. * Repeats for 20 times. * Makes a request to the origin site with waiting room enabled. * Logs request details. * Pauses for 10 seconds before refreshing the page to make another request to the origin site. ![User attributes](https://developers.cloudflare.com/_astro/user-attributes.CMfB7b6L_6qoKz.webp) Per the plan above, each [Thread Group ↗](https://jmeter.apache.org/usermanual/test%5Fplan.html#thread%5Fgroup) performs the above action once. The user traffic ramps up within the first minute and keeps a sustained traffic for the next three minutes before users leave the site. You can send more or less traffic than what is being sent in this example by updating these properties. ![Visualizing number of threads](https://developers.cloudflare.com/_astro/threads.BTLucBgH_fTIip.webp) ## 3\. Analyze results To analyze the results of your test, you can query Waiting Room Analytics (Beta) via Cloudflare’s GraphQL API to check Total Active Users and Queued Users for each minute of your load test. Example Curl Statement Terminal window ``` echo '{ "operationName": "UsersQueuedOverTimeQuery", "variables": { "filter": { "datetime_geq": "2022-10-17T15:34:00Z", "datetime_leq": "2022-10-17T15:40:00Z", "waitingRoomId": "" }, "zoneId": "" }, "query": "query UsersQueuedOverTimeQuery($zoneId: string, $filter: ZoneWaitingRoomAnalyticsAdaptiveGroupsFilter_InputObject) {\n viewer {\n zones(filter: {zoneTag: $zoneId}) {\n timeseries: waitingRoomAnalyticsAdaptiveGroups(limit: 5000, filter: $filter, orderBy: [datetimeMinute_ASC]) {\n avg {\n totalActiveUsers\n totalActiveUsersConfig\n totalQueuedUsers\n __typename\n }\n max {\n totalQueuedUsers\n totalActiveUsers\n totalActiveUsersConfig\n __typename\n }\n min {\n totalActiveUsersConfig\n __typename\n }\n dimensions {\n ts: datetimeMinute\n __typename\n }\n __typename\n }\n total: waitingRoomAnalyticsAdaptiveGroups(limit: 1, filter: $filter) {\n max {\n totalQueuedUsers\n totalActiveUsers\n __typename\n }\n __typename\n }\n __typename\n }\n __typename\n }\n}\n" }' | tr -d '\n' | curl \ -X POST ``` From our test, we got the following results (these are extracted from results of the query for readability): * 15:35:00 UTC * `"totalActiveUsers": 137,` * `"totalActiveUsersConfig": 300,` * `"totalQueuedUsers": 0` * 15:36:00 UTC * `"totalActiveUsers": 200,` * `"totalActiveUsersConfig": 300,` * `"totalQueuedUsers": 0` * 15:37:00 UTC * `"totalActiveUsers": 200,` * `"totalActiveUsersConfig": 300,` * `"totalQueuedUsers": 0` * 15:38:00 UTC * `"totalActiveUsers": 200,` * `"totalActiveUsersConfig": 300,` * `"totalQueuedUsers": 0` The first minute mark, 15:35:00 UTC, shows 137 active users past the waiting room. This is because our traffic was set to gradually ramp up within the first minute and the test did not start exactly at the minute mark. When data was aggregated for the following minute, 15:36:00 UTC, the waiting room reported the total 200 users active we expected on the site as each “user” made subrequests. The active user count remained stable at 200 as long as it received subrequests from the traffic sent by the load test. Note Obtain your API token from the dashboard. Make sure your API token grants access to the **Analytics** resource. For more information on how to get the API token, follow the [Configure Analytics API token](https://developers.cloudflare.com/analytics/graphql-api/getting-started/authentication/api-token-auth/) guide. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/additional-options/","name":"Additional options"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/additional-options/test-waiting-room/","name":"Test a waiting room"}}]} ``` --- --- title: Waiting Room Bypass Rules description: A Waiting Room Bypass Rule is a type of Waiting Room Rule built on Cloudflare’s Ruleset Engine and managed via the Waiting Room API. A Waiting Room Bypass Rule allows you to indicate specific traffic or areas of your site or application that you do not want a waiting room to apply to. Each bypass rule is created and managed at the individual waiting room level for precise control over your waiting room traffic. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/additional-options/waiting-room-rules/bypass-rules.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Waiting Room Bypass Rules A Waiting Room Bypass Rule is a type of Waiting Room Rule built on Cloudflare’s Ruleset Engine and managed via the Waiting Room API. A Waiting Room Bypass Rule allows you to indicate specific traffic or areas of your site or application that you do not want a waiting room to apply to. Each bypass rule is created and managed at the individual waiting room level for precise control over your waiting room traffic. To indicate where you want your bypass rules to apply, write [custom logic](https://developers.cloudflare.com/ruleset-engine/rules-language/) using the [fields](https://developers.cloudflare.com/ruleset-engine/rules-language/fields/reference/) available via the Cloudflare Ruleset Engine, except the following: * `cf.threat_score` and fields starting with `cf.bot_management` * HTTP response fields Please be advised that the waiting room will not apply to all the traffic that matches the expressions written for bypass rules and will not be counted as active users. No Waiting Room features, including but not limited to, Event pre-queueing, Reject queueing method, or Queue-all will apply to this traffic. Be mindful of this when creating and enabling Bypass Waiting Room rules. Only use bypass rules for traffic you are confident will not overwhelm your origin or cause significant traffic surges. Note Only some customers can create Waiting Room rules. For more details, refer to our [Plans](https://developers.cloudflare.com/waiting-room/plans/) page. ## Common Use Cases * **Path/URL Exclusion**: Bypass specific paths or URLs under the path you have configured for your waiting room, if you do not want your waiting room to apply to these paths. * **Administrative Bypass**: Allow internal site administrators to always bypass the waiting room, commonly identified by IP addresses. * **Geo-targeting**: Exclude certain countries from being queued. * **Query String Exclusion**: Exclude specific query strings under the path you have configured for your waiting room. * **Exclude file extensions**: Prevent waiting room from applying to certain file extensions, such as `.js` that you utilize on your waiting room HTML template so that they render properly. ### A note on subrequests Along with the query string(s) or paths you would like to exclude, make sure to include in your expression any paths or file types that subrequests may be hitting so that these assets or paths do not have waiting room applied as well. Otherwise, these subrequests will be getting the waiting room cookie since they are still covered by the waiting room. These could include anything like images, JavaScript files, CSS files, etc. You can also configure the rule to bypass the waiting room for any paths of a file type by bypassing if a request ends with `.js`, `.css`, `.png`, etc., so you do not have to manually configure each path those assets may be stored under. Example condition: `ends_with(http.request.uri.path, ".js")` ## Create Waiting Room Bypass Rules in the dashboard To create a new bypass rule: 1. In the Cloudflare dashboard, go to the **Waiting Room** page. [ Go to **Waiting Room** ](https://dash.cloudflare.com/?to=/:account/:zone/traffic/waiting-rooms) 2. Expand a waiting room and select **Manage rules**. 3. Select **Create new bypass rule**. 4. Enter a descriptive name for the rule in **Rule name**. 5. Under **When incoming requests match**, define the rule expression. Use the **Field** drop-down list to choose an HTTP property. For each request, the value of the property you choose for **Field** is compared to the value you specify for **Value** using the operator selected in **Operator**. 6. Under **Then**, the Bypass Waiting Room action is automatically selected. Before saving, review your expression and ensure that the traffic that matches your expression is the traffic that you do not want the waiting room to apply to. 7. To save and deploy your rule, select **Save and Deploy**. If you are not ready to deploy your rule, select **Save as Draft**. ### Operators and grouping symbols * Comparison operators specify how values defined in an expression must relate to the actual HTTP request value for the expression to return true. * Logical operators combine two expressions to form a compound expression and use order of precedence to determine how an expression is evaluated. * Grouping symbols allows you to organize expressions, enforce operator precedence, and nest expressions. For examples and usage, refer to [Operators and grouping symbols](https://developers.cloudflare.com/ruleset-engine/rules-language/operators/) in the Rules language documentation. ## Manage Rules via the Waiting Room API You can manage, delete, and create bypass rules for your waiting room via the [Waiting Room API’s](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/rules/methods/get/). A bypass rule is a Waiting Room Rule that utilizes the `bypass_waiting_room` action. When creating a Bypass Waiting Room Rule via API, make sure you: * Have already created and saved a waiting room you want the rule to apply to. * Define the expression to indicate which traffic you would like to bypass your waiting room. * Set the rule action to `bypass_waiting_room`. Create a waiting room rule by appending the following endpoint in the Waiting Room API to the Cloudflare API base URL. New waiting room rules will be added after any existing rules. ``` POST zones/{zone_id}/waiting_rooms/{room_id}/rules ``` Configure your bypass rule with the following required and optional parameters: * **Description** (optional) - Give your rule a description to help keep a record of the purpose of this bypass rule. * **Expression** (required) - Define the rule expression indicating which traffic to apply the bypass rule to. * **Action** (required) - Define the action to take when expression evaluates to true. Set this to `bypass_waiting_room`. * **Enabled** (optional) - This will default to true. If you do not wish to deploy your rule, you must set this to false. ### ​​API Examples Bypass a path under your waiting room and all of its subpaths If your waiting room is configured at `example.com/` and you would like all traffic visiting `example.com/bypassme` and all of its subpaths. In this example, we also want to ensure any subrequests of `js`, `css`, or `png` from also bypass the waiting room to ensure all assets are loaded properly on the paths being bypassed. Note that in this example, all requests ending in `js`, `css` or `png` will bypass the waiting room regardless of the subpath. If this is not your intended use case, please alter the expression to suit your specific requirements and site architecture. Create Waiting Room Rule ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID/rules" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "description": "subpath bypass", "expression": "starts_with(http.request.uri.path, \"/bypassme\") or ends_with(http.request.uri.path, \".js\") or ends_with(http.request.uri.path, \".css\") or ends_with(http.request.uri.path, \".png\")", "action": "bypass_waiting_room" }' ``` Allow a defined list of IPs to bypass the waiting room Create Waiting Room Rule ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID/rules" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "description": "ip list bypass", "expression": "ip.src in $bypass_ip_list", "action": "bypass_waiting_room" }' ``` ### Other API options for managing bypass rules Through the Waiting Room API, you can also do the following to manage bypass rules by using the Waiting Room rules API calls: * **List Waiting Room Rules**: Lists rules for a waiting room. * **Replace Waiting Room Rules**: Replaces all rules for a waiting room. * **Patch Waiting Room Rules**: Updates a rule for a waiting room. * **Delete Waiting Room Rules**: Deletes a rule for a waiting room. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/additional-options/","name":"Additional options"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/additional-options/waiting-room-rules/","name":"Waiting Room Rules"}},{"@type":"ListItem","position":5,"item":{"@id":"/waiting-room/additional-options/waiting-room-rules/bypass-rules/","name":"Waiting Room Bypass Rules"}}]} ``` --- --- title: Glossary description: Review the definitions for terms used across Cloudflare's Waiting Room documentation. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/glossary.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Glossary Review the definitions for terms used across Cloudflare's Waiting Room documentation. | Term | Definition | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | downtime | Downtime is the duration during which a system, service, or equipment is not operational or unavailable for use. | | error page | An error page is a webpage shown to users when they try to access a specific webpage or resource that is unavailable due to a server error, broken link, or other issues. It typically includes details about the encountered error and offers potential solutions or guidance to help users navigate the problem. | | iFrame | An iFrame, short for Inline Frame, is an HTML element used to embed and display external content within a webpage, allowing the incorporation of another document or web page seamlessly within the main document. | | JSON-friendly | JSON-friendly refers to data or formats that are easily and naturally represented in JSON (JavaScript Object Notation), a lightweight data interchange format, without requiring complex transformations or modifications. | | legitimate traffic | Legitimate traffic refers to authorized and permissible network activity, data transmissions, or communications that adhere to established norms and rules within a given system or network. | | non-browser traffic | Non-browser traffic refers to data exchanges and communication occurring between devices or systems that do not involve web browsers, such as a mobile app or web apps. | | SEO crawlers | SEO crawlers, or web crawlers, are automated programs employed by search engines to systematically browse and index web content, gathering information about the structure and relevance of pages to determine search result rankings. | | Set-Cookie | Set-Cookie is an HTTP header used by web servers to send a cookie to a user's browser during an HTTP response, enabling the server to store information on the client side, often used for session management and user preferences. | | traffic management | The process of controlling and optimizing the flow of network data to ensure efficient and reliable communication. | | virtual waiting room | A virtual waiting room is an online system or feature that manages and controls access to a website or service during periods of high traffic, preventing server overload by placing users in a queue until they can be accommodated, ensuring a more equitable and efficient user experience. | ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/glossary/","name":"Glossary"}}]} ``` --- --- title: Control user session settings description: Adjust these settings to control how long a user can hold their place on your site after leaving the waiting room. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/control-user-session.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Control user session settings Adjust these settings to control how long a user can hold their place on your site after leaving the waiting room. ## Session duration Once on your site, a user is considered active as long as they make an HTTP request to any URL covered by your waiting room once every **session duration** minutes. Each new request restarts a user’s time to stay active equal to **session duration**. ## Disable session renewal to limit browsing time You can limit each user’s time on your site to only one session duration by checking the box next to Disable Session Renewal from the dashboard. Once a user has been active on your site for **session duration** minutes, if there is active queueing, that user will be sent to the back of the queue. If there is not an active queue when **session duration** minutes is over, this user will be given a new waiting room cookie and counted as a new user again. ## Revoke a user’s session using origin commands To terminate a user's session when they perform a specific action, you can send a command to the waiting room using an HTTP header on the response from your origin. This command tells the waiting room to revoke the session of the user associated with the current response. This allows spots to open up more dynamically and may increase throughput from your queue. To enable this feature in the Cloudflare Dashboard, check the box next to Allow session termination via origin commands from the dashboard. To enable this feature through the [Cloudflare API](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/update/), update the `enabled_origin_commands` property to include the value `”revoke”` in the list of enabled origin commands. Then, to return a revocation origin command and revoke the user's session associated with the current request, add the `Cf-Waiting-Room-Command: revoke` HTTP header to the response from your origin. To get the number of sessions revoked, you can query `sessionsRevoked` metrics from your [Waiting Room analytics](https://developers.cloudflare.com/waiting-room/waiting-room-analytics/#graphql-analytics) data via GraphQL API. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/control-user-session/","name":"Control user session settings"}}]} ``` --- --- title: Control waiting room traffic description: To change whether and how traffic reaches a waiting room, update the values for Enabled, Queue All, and Queueing Method on your waiting room. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/control-waiting-room.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Control waiting room traffic To change whether and how traffic reaches a waiting room, update the values for **Enabled**, **Queue All**, and **Queueing Method** on your waiting room. ## Enable a waiting room To enable a waiting room: 1. Go to **Traffic** \> **Waiting Room**. 2. On a waiting room, set **Enabled** to **On**. ## Queue options By default, an active waiting room puts visitors in a queue when traffic approaches the target thresholds defined in **Total active users** and **New users per minute**. Refer to [Queueing activation](https://developers.cloudflare.com/waiting-room/how-to/monitor-waiting-room/#queueing-activation) for more information. However, if you want all visitors to be queued for a predefined amount of time — in preparation for a product release or other time-based event — use the [Create scheduled events](https://developers.cloudflare.com/waiting-room/additional-options/create-events/) option. You may also use the **Queue-all** option on a waiting room as an emergency stop to all traffic during unexpected or temporary downtime. As long as the waiting room is active and **Queue-all** is enabled, no traffic will reach your application. ### Queue visitors when necessary To queue visitors only when necessary: 1. Go to **Traffic** \> **Waiting Room**. 2. On a waiting room, set **Enabled** to **On**. 3. Your waiting room will begin queueing visitors once it approaches the target traffic thresholds defined in [**Total active users**](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/) and in [**New users per minute**](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/). ### Queue all visitors To queue all visitors prior to a time-based offering, set up a pre-queue as part of a [waiting room event](https://developers.cloudflare.com/waiting-room/additional-options/create-events/#create-an-event-from-the-dashboard). To start queueing all new visitors without a scheduled event: 1. Go to **Traffic** \> **Waiting Room**. 2. On a waiting room: 1. Ensure **Enabled** is set to **On**. 2. Set **Queue-all** to **On**. 3. Your waiting room will begin queueing all new visitors and will not allow any new visitors to the path protected by your waiting room. Queue-all will override all other waiting room settings, including event settings. Note Only new visitors will be queued. Active users that are already on your website will continue there and will not return to the queue until their session expires. 1. To begin allowing visitors to the path protected by your waiting room, set **Queue-all** to **Off**. ## Queueing method For more details about queueing method, refer to [Queueing methods](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/control-waiting-room/","name":"Control waiting room traffic"}}]} ``` --- --- title: Create a waiting room description: You can create a waiting room from the dashboard or via API. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/create-waiting-room.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Create a waiting room You can create a waiting room from the dashboard or via API. Note For additional context on creating a waiting room, refer to [Get started](https://developers.cloudflare.com/waiting-room/get-started/). * [ Dashboard ](#tab-panel-6909) * [ API ](#tab-panel-6910) 1. Within your application, go to **Traffic** \> **Waiting Room**. 2. Select **Create**. 3. Customize the [settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/) for your waiting room. For additional guidance refer to [Best practices](https://developers.cloudflare.com/waiting-room/reference/best-practices/). 4. Select **Next**. 5. In this section, you can choose whether to enable [Turnstile](https://developers.cloudflare.com/turnstile/) for your waiting room. If you select **Yes**, you will need to choose your [Widget mode](https://developers.cloudflare.com/turnstile/concepts/widget/) and define the action to take if a turnstile challenge fails. The available Widget modes and actions depend on your plan type. Refer to the [Plans](https://developers.cloudflare.com/waiting-room/plans/) for more details. 6. If you wish to [customize your waiting room](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/), update the HTML and CSS as needed. If you are using this waiting room to manage traffic for your mobile app or API, enable the JSON response toggle. Make sure that you have set up a [JSON friendly response](https://developers.cloudflare.com/waiting-room/how-to/json-response/) for your client (mobile or web app). 7. Select the **Queuing status code** to determine the HTTP status code that is returned when a user is in the waiting room. 8. Select **Next**. 9. Review your settings before saving. If you customized your waiting room, make sure to [preview the result](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/#preview-waiting-room). 10. Select **Save**. Your new waiting room will be enabled by default. To create a Waiting Room using the API, send a [POST request](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/) to the `/zones/{zone_identifier}/waiting_rooms` endpoint: * For parameter references, refer to [Configuration settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/) * For authentication instructions, refer to [Create an API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). * For help with endpoints and pagination, refer to [Make API calls](https://developers.cloudflare.com/fundamentals/api/how-to/make-api-calls/). Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Write` Create waiting room ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "shop_waiting_room", "description": "Waiting room for webshop", "host": "shop.example.com", "path": "/shop", "queue_all": true, "new_users_per_minute": 200, "total_active_users": 300, "session_duration": 1, "disable_session_renewal": false, "json_response_enabled": false, "queueing_method": "fifo", "queueing_status_code": 202, "cookie_attributes": { "samesite": "auto", "secure": "auto" } }' ``` The response contains the complete definition of the newly created Waiting Room. Response ``` { "success": true, "errors": [], "messages": [], "result": [ { "id": "1111111111111111111111", "created_on": "2023-01-01T05:20:00.12345Z", "modified_on": "2023-01-01T05:20:00.12345Z", "name": "shop_waiting_room", "description": "Waiting room for webshop", "host": "shop.example.com", "path": "/shop", "queue_all": true, "new_users_per_minute": 200, "total_active_users": 300, "session_duration": 1, "disable_session_renewal": false, "json_response_enabled": false, "queueing_method": "fifo", "queueing_status_code": 202, "cookie_attributes": { "samesite": "auto", "secure": "auto" } } ] } ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/create-waiting-room/","name":"Create a waiting room"}}]} ``` --- --- title: Customize a waiting room description: You can customize your waiting room from the dashboard or via API. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/customize-waiting-room.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Customize a waiting room You can customize your waiting room from the dashboard or via API. ## Customize a waiting room from the dashboard To design and preview the appearance of a waiting room, select the **Customization** tab in the **Create waiting room** page. Cloudflare offers options to customize the appearance of your waiting room: * [Default waiting room](#default-waiting-room): An unbranded waiting room that displays an estimated waiting time to visitors. * Select a language for your default waiting room page. You can choose from the following languages: English, Arabic, German, Spanish, French, Indonesian, Italian, Japanese, Korean, Dutch, Polish, Portuguese (Brazilian), Turkish and Chinese (Simplified and Traditional). * [Custom waiting room](#custom-waiting-room): Edit template text or create your own HTML code: * Customize both HTML or CSS content, including fonts, colors, static images, additional languages and more. * Edit content directly in the dashboard or import relevant files. * [Return a JSON-friendly waiting room response](https://developers.cloudflare.com/waiting-room/how-to/json-response/): Toggle to also enable a JSON response with a user's status in the waiting room. ### Default waiting room To choose the default, unbranded waiting room: 1. Select a waiting room. 2. Go to the **Customization** step. 3. Select **Default waiting room**. 4. Select the language for your waiting room default page. ### Custom waiting room Note Only certain customers can customize their waiting rooms. For more details, refer to our [Plans](https://developers.cloudflare.com/waiting-room/plans/) page. To customize a waiting room: 1. Select a waiting room. 2. Go to the **Customization** step. 3. Select **Custom waiting room**. You can edit the HTML code directly in the text box: * Select **Download default template** to download a HTML file containing the default template content to your computer. * Select **Download** to download a HTML file containing the text box content to your computer. * Select **Copy** to copy the text from the text box to your clipboard, then paste it into an editor of your choice. The template text contains [code to display the wait time](#display-wait-time). If you want to display the estimated wait time to visitors, do not delete this content. #### Upload an HTML file 1. Select **Import** to upload a HTML file from your computer. 2. Select the file in the dialog and select **Open**. The HTML file size limit is 1,048,576 bytes (1 MB). Make further edits in the text box. Include the [code to display the wait time](#display-wait-time) to display the estimated queue time on the waiting room page or create your own custom page using [available variables](#available-variables). #### Display wait time The following content in the `
` section of the template HTML code displays the wait time: ```

``` The following script within the `` section after `
` fetches the wait time: ``` ``` #### Turnstile variable If you are using Turnstile for your customized waiting room, you will need to ensure the `turnstile` variable is added. The default queuing page template and any newly created custom templates already include this variable. If you have an existing custom HTML template and wish to enable the Turnstile integration, you will need to add `{{{turnstile}}}` somewhere in the template to let Waiting Room know where the widget should be placed. Waiting Room uses Mustache templates, so including raw HTML within your template without escaping requires three curly braces instead of two. ``` Waiting Room

You are currently in the queue.

{{#waitTimeKnown}}

Your estimated wait time is {{waitTimeFormatted}}.

{{/waitTimeKnown}} {{^waitTimeKnown}}

Your estimated wait time is unknown.

{{/waitTimeKnown}} {{#turnstile}}

Please complete this challenge so we know you're a human:

{{{turnstile}}} {{/turnstile}} ``` When using Infinite Queue (especially with managed challenges which may be interactive), you may want to let users know that they will not be in the queue until they complete the challenge. #### Available variables When you create a waiting room with custom HTML, you can have access to several variables to customize your response. For a full list of variables, refer to the `json_response_enabled` parameter in the [Cloudflare API docs](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/). #### Multiple-language support Customizable waiting rooms can display text in any language supported by the UTF-8 character set. To display estimated wait time, you can use numeric variables like `waitTime` and `waitTimeHours` within your waiting room template, regardless of user language. However, at the time, the following variables are only available in English: `waitTimeFormatted`, `timeUntilEventStartFormatted`, and `timeUntilEventEndFormatted`. If you would like to display different languages within your custom waiting room depending on path or subdomain, you can add JavaScript code to your custom HTML to do so. Below you can find a couple of starter templates that you can use as an example to start from: * To display a different language based on path, download this [template](https://developers.cloudflare.com/waiting-room/static/index.path.html.txt). The template displays the content in English if the path contains `en` or as a default, Japanese if the path contains `jp`, French if the path contains `fr`, and Spanish if the path contains `es`. * To display a different language based on subdomain, download this [template](https://developers.cloudflare.com/waiting-room/static/index.subdomain.html.txt). The template displays the content in English as a default or if the subdomain contains `en`, Japanese if the subdomain contains `jp`, French if the subdomain contains `fr`, and Spanish if the subdomain contains `es`. Download either of these templates and customize them however you would like. Update the path or subdomain to reflect your site’s language selection structure. You may edit these templates to include other languages by adding translations to the `translations` object for each of the locales. #### Resource hosting If you are using images or other resources for your customized waiting room, **do not** host those assets on the hostname covered by your waiting room. Otherwise, any requests for these assets will not be able to pass through the waiting room. ### Preview waiting room To preview the appearance of a waiting room: 1. In your application, go to **Traffic** \> **Waiting Room**. 2. Either [create a waiting room](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/) or [edit an existing one](https://developers.cloudflare.com/waiting-room/how-to/edit-delete-waiting-room/). 3. Go to the **Review** step. 4. Select **Preview waiting room**: * Choose **Queueing** to display the waiting room appearance when it is enabled on the dashboard and **Queue-all** is not enabled. * Choose **Queue-All** to display the waiting room appearance when it is enabled on the dashboard and **Queue-all** is enabled. When **Queue-all** is enabled for a waiting room, the estimated wait time is not displayed. ### Troubleshooting If you notice something unexpected when previewing your waiting room, review your custom code for proper syntax. Often, you might forget to close each tag with its appropriate closing tag (the tag name with a `/`). ## Customize a waiting room via API 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](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/): Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Write` Patch waiting room ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID" \ --request PATCH \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "webshop-waiting-room", "host": "example.com", "new_users_per_minute": 200, "total_active_users": 300, "custom_page_html": "

Include custom HTML here

" }' ``` Response: ``` { "success": true, "errors": [], "messages": [], "result": [ { "id": "1111111111111111111111", "name": "webshop-waiting-room", "description": "Waiting room for webshop", "host": "example.com", "path": "/shop", "suspended": false, "queue_all": false, "new_users_per_minute": 200, "total_active_users": 300, "session_duration": 1, "disable_session_renewal": false, "json_response_enabled": false, "queueing_method": "FIFO", "cookie_attributes": { "samesite": "auto", "secure": "auto" }, "custom_page_html": "

Include custom HTML here

", "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: ``` POST https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms/preview ``` In the request body, include the customized HTML content in the `custom_html` field: ``` { "custom_html": "

Include custom HTML here

" } ``` 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: Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Write` Create a custom waiting room page preview ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/preview" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "custom_html": "

Include custom HTML here

" }' ``` The preview endpoint returns a temporary URL in the response body where you can preview your custom page: ``` { "result": { "preview_url": "https://waitingrooms.dev/preview/111111111111" }, "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](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/page/methods/preview/), 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. ``` GET https://waitingrooms.dev/preview/{preview_id} ``` The link in the response displays the content of the `custom_page_html` field, rendered with [mustache ↗](https://mustache.github.io). Use the optional `force_queue` query parameter to preview the waiting room web page when all traffic is force-queued. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/customize-waiting-room/","name":"Customize a waiting room"}}]} ``` --- --- title: Edit and delete waiting rooms description: You can manage your waiting rooms using the Waiting Room dashboard or the API. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/edit-delete-waiting-room.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Edit and delete waiting rooms You can manage your waiting rooms using the [Waiting Room dashboard](https://developers.cloudflare.com/waiting-room/how-to/waiting-room-dashboard/) or the [API](https://developers.cloudflare.com/waiting-room/reference/waiting-room-api/). Note For details about updating an active waiting room, refer to [Best practices](https://developers.cloudflare.com/waiting-room/reference/best-practices/). ## Use the dashboard ### Edit a waiting room 1. In your application, go to **Traffic** \> **Waiting Room**. 2. On a record, select **Edit**. 3. Select **Settings**. 4. Edit the settings. For a description of settings, refer to [Configuration settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/). 5. Select **Next**. If you have access to [customized templates](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/), you could also adjust the template. 6. Once you get to **Review**, select **Save**. ### Delete a waiting room 1. In your application, go to **Traffic** \> **Waiting Room**. 2. On a record, select **Delete**. 3. Select **Delete** again. ## Use the API ### Edit a waiting room [Replace ↗](https://api.cloudflare.com#waiting-room-update-waiting-room) a configured waiting room by appending the following endpoint to the Cloudflare API base URL. Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Write` Update waiting room ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "webshop-waiting-room", "host": "example.com", "new_users_per_minute": 200, "total_active_users": 300 }' ``` [Update ↗](https://api.cloudflare.com#waiting-room-patch-waiting-room) a configured waiting room by appending the following endpoint to the Cloudflare API base URL. Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Write` Patch waiting room ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID" \ --request PATCH \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "webshop-waiting-room", "host": "example.com", "new_users_per_minute": 200, "total_active_users": 300 }' ``` You only need to include the fields you want to update in the payload of the PATCH request. ### Delete a waiting room Delete a waiting room by appending the following endpoint in the [Waiting Room API ↗](https://api.cloudflare.com#waiting-room-delete-waiting-room) to the Cloudflare API base URL. Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Write` Delete waiting room ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID" \ --request DELETE \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/edit-delete-waiting-room/","name":"Edit and delete waiting rooms"}}]} ``` --- --- title: Get JSON response for mobile and other non-browser traffic description: If you need to manage traffic in a non-browser environment such as a mobile app or web app, Cloudflare provides a JSON-friendly waiting room that can be consumed via your API endpoints: image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) ### Tags [ JSON ](https://developers.cloudflare.com/search/?tags=JSON) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/json-response.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Get JSON response for mobile and other non-browser traffic If you need to manage traffic in a non-browser environment such as a mobile app or web app, Cloudflare provides a JSON-friendly waiting room that can be consumed via your API endpoints: 1. When a user is queued, we return our own JSON response. 2. When a user leaves the waiting room, we forward the request to your origin server and return the response from your origin server (be it JSON, XML, an HTML page, etc.). Important Turnstile is not supported for Waiting Room JSON responses. Turnstile challenges are only enforced for browser-based (HTML) responses. If your application relies on JSON responses (for example, mobile apps, APIs, or other non-browser traffic), Turnstile will be disabled and cannot be enabled for these requests. In order to consume the waiting room response in the JSON format, take the following steps: ## Step 1 – Enable JSON response To receive a JSON response, you first need to enable that option in your waiting room. * **Via the dashboard**: When [customizing a waiting room](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/), enable **JSON Response**. * **Via the API**: When [creating a waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/), set `json_response_enabled` to true. ## Step 2 – Get JSON data Make a request to your waiting room endpoint with the header `Accept: application/json`. Note that the header has to match exactly `Accept: application/json`. If it is anything else or has any additional content such as `Accept: application/json, text/html` the response will not return in the JSON format. You must retry the request every `refreshIntervalSeconds` in order for users to advance in the queue. Request ``` curl "https://example.com/waitingroom" \ --header "Accept: application/json" ``` Response ``` { "cfWaitingRoom": { "inWaitingRoom": true, "waitTime": 5, "waitTimeKnown": true, "waitTimeFormatted": "5 minutes", "queueIsFull": false, "queueAll": false, "lastUpdated": "2021-08-03T23:46:00.000Z", "refreshIntervalSeconds": 20 } } ``` ## Cookies in the request header Waiting Room is driven by a waiting room cookie that determines the position of the user in the queue. Because of this, the cookie is updated in the response headers for each request. For each request to an endpoint protected by Waiting Room, the application must include the up-to-date cookie retrieved during the previous request. This is mandatory regardless of a user having been queued or not. If a request does not include a cookie, the waiting room will assume this is a new user and will return a new cookie in the response header. Consequently, this will place the user at the end of the queue. Thus, when consuming the waiting room in a non-browser environment it is important to include the waiting room cookie in the request header and keep it updated after each request. Refer to the [Waiting Room cookies](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/), for more information. ## Advancing in the queue In a browser environment, the page automatically refreshes every `refreshIntervalSeconds` to ensure that the user advances in the queue. In a non-browser environment, where the Waiting Room JSON-friendly API is being consumed, it is expected that your backend service (or API) also refreshes/makes a request to the Waiting Room configured endpoint every `refreshIntervalSeconds` to ensure the advancing of the user in the queue. These are some of the places where the JSON-friendly response can be consumed (this list is not exhaustive): 1. In a mobile app traffic * **Integrate Waiting Room variables** – Create a new template in your mobile app to receive the JSON response. For a full list of these variables, refer to the `json_response_enabled` parameter in the [Cloudflare API docs](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/). * **Allow cookies** – As mentioned above, a waiting room [requires cookies](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/), and your mobile app will need to support cookies. For ease of use, consider using a cookie manager like [CookieJar ↗](https://pkg.go.dev/net/http#CookieJar). * **Consume JSON data** \- Make a request to the Waiting Room endpoint with the `Accept: application/json` header. 2. Inside Cloudflare Workers (or in your own backend service) * **Integrate Waiting Room variables** – Expect a JSON response in your backend API. For a full list of these variables, refer to the `json_response_enabled` parameter in the [Cloudflare API docs](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/). * **Include cookies in the request header** – As mentioned above, a waiting room [requires cookies](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/), and your backend API will need to support cookies. For ease of use, consider using a cookie manager like [CookieJar ↗](https://pkg.go.dev/net/http#CookieJar). * **Enable JSON response** \- Via the dashboard or via the API. * **Consume JSON data** \- Make a request to the Waiting Room endpoint with the `Accept: application/json` header. Here is an example, demonstrating the usage of the waiting room endpoint inside a Worker. The request headers include the necessary `accept` and `cookie` header values that are required by the Waiting Room API. The accept header ensures that a JSON-friendly response is returned, if a user is queued. Otherwise, if the request is sent to the origin, then whatever the response origin returns gets returned back. In this example, a hardcoded `__cfwaitingroom` value is embedded in the cookie field. In a real-life application, however, we expect that a cookie returned by the Waiting Room API is used in each of the subsequent requests to ensure that the user is placed accordingly in the queue and let through to the origin when it is the users turn. JavaScript ``` const waitingroomSite = "https://examples.cloudflareworkers.com/waiting-room"; export default { async fetch(request, env, ctx) { const init = { headers: { accept: "application/json", cookie: "__cfwaitingroom=F)J@NcRfUjXnZr4u7x!A%D*G-KaPdSgV", }, }; return fetch(waitingroomSite, init) .then((response) => response.json()) .then((response) => { if (response.cfWaitingRoom.inWaitingRoom) { return Response("in waiting room", { "content-type": "text/html" }); } return new Response(response); }); }, }; ``` Note Only Advanced Waiting Room customers can support JSON-friendly format with their waiting rooms. For more details, refer to our [Plans page](https://developers.cloudflare.com/waiting-room/plans/). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/json-response/","name":"Get JSON response for mobile and other non-browser traffic"}}]} ``` --- --- title: Monitor waiting room status description: You can monitor the status of your waiting rooms using the dashboard or the API. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/monitor-waiting-room.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Monitor waiting room status You can monitor the status of your waiting rooms using the [dashboard](#status-in-the-dashboard) or the [API](#status-in-the-api). Note that the **Total active users** and **Queued users** shown in the dashboard, as well as through API endpoints are estimates. That data corresponding to each of these metrics is cached for around 30 seconds after the time it takes to be synced from all data centers globally. Therefore, the status will range between 20-50 seconds in the past, depending on the exact moment the data was queried, aggregated, as well as the age of the cache. Refer to [Waiting Room Analytics](https://developers.cloudflare.com/waiting-room/waiting-room-analytics/) for more details about the traffic going through your waiting room. ## Status in the dashboard Open the **Waiting Room** dashboard to view the list of your waiting rooms. The **Status** column displays the current state of the waiting room: * **Not queueing**: * Waiting room enabled, but has not reached traffic threshold to send visitors to waiting room. * Shows estimated number of users in the application. * **Queueing**: * Waiting room enabled and sending visitors to waiting room. * Shows estimated number of users in the queue. * On hover, shows maximum wait time expected for users. * **Disabled**: The waiting room is suspended. * **Queue-all**: * Forces all traffic to queue in the waiting room. * On hover, shows estimated number of users in the queue. ## Status in the API [Check whether traffic is queueing in a configured waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/statuses/methods/get/) by appending the following endpoint to the Cloudflare API base URL: Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Read` * `Waiting Rooms Write` Get waiting room status ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID/status" \ --request GET \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` The response is: * `queueing` if visitors are currently queueing in the waiting room. * `not_queueing` if the room is empty or if the waiting room is suspended. To check whether a configured waiting room is suspended or whether the traffic is force-queued to the waiting room, append the following endpoint to the Cloudflare API base URL. Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Waiting Rooms Read` * `Waiting Rooms Write` Waiting room details ``` curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID" \ --request GET \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` The endpoint above [fetches all settings](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/get/) for a configured waiting room: Terminal window ``` "success": true, "errors": [], "messages": [], "result": { "id": "REDACTED", "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", "suspended": false, "host": "shop.example.com", "path": "/shop", "queue_all": true, "new_users_per_minute": 200, "total_active_users": 300, "session_duration": 1, "disable_session_renewal": false, "json_response_enabled": false, "queueing_method": "random", "cookie_attributes": { "samesite": "auto", "secure": "auto" }, "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}" } ``` The value of `suspended` indicates whether a waiting room is activated or suspended: * `false`: The waiting room is activated. * `true`: The waiting room is suspended. The value of `queue_all` indicates whether all traffic is forced to queue in the waiting room: * `false`: Visitors are diverted to the waiting room only if traffic exceeds the configured threshold. * `true`: All traffic is forced to queue in the waiting room, and no traffic passes from the waiting room to the origin. ## Queueing activation Waiting Room queues traffic at the data-center level to increase scalability, letting each data center make decisions independently. Because of this design, the configured traffic limits of a waiting room are target values which your waiting room will work to keep your traffic volumes near. A waiting room might queue traffic from a specific data center before the waiting room reaches its limit of `new_users_per_minute` or `total_active_users`. Waiting Room also continuously monitors the rate of users entering throughout each minute, and not just at the end of the minute. Therefore, if at the beginning of your minute, a large fraction of your set `new_users_per_minute` value already joined, we may start queueing users, even if the overall `new_users_per_minute` value that is reached for that minute is not hit. To help prevent a waiting room from active queueing, increase the values for `new_users_per_minute` and/or `total_active_users`. For more information about how Waiting Room makes queueing decisions, review our [blogpost ↗](https://blog.cloudflare.com/how-waiting-room-queues). Note Note that Waiting Room is designed to handle legitimate traffic. If you notice frequent or abnormal queueing behavior, ensure that you are properly handling malicious and automated traffic using Cloudflare security products. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/monitor-waiting-room/","name":"Monitor waiting room status"}}]} ``` --- --- title: Place a waiting room description: When configuring a waiting room, you need to indicate which pages the waiting room will cover. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/place-waiting-room.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Place a waiting room When [configuring a waiting room](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/), you need to indicate which pages the waiting room will cover. Your waiting room requires at least one hostname and path in its configuration settings. There is an implied wildcard after the path, meaning the waiting room will also apply to any subpaths. When there is an active queue, all new users will enter the queue at any URLs covered by this hostname and path combination. If you have multiple waiting rooms, the waiting room with the most specific subpath takes precedence. ## Apply to multiple hostnames and paths Advanced Waiting Room customers can apply a single waiting room to multiple hostnames and paths. To do so via the UI, after adding the first hostname and path, select **Add Hostname and Path** and then input the next hostname and path combination you would like the waiting room to cover. If adding more than one hostname and path for a single waiting room, you must also create a unique waiting room cookie by filling out the Custom cookie field. To add multiple hostnames and paths via the API, utilize the `additional_routes` field and customize the cookie suffix with the `cookie_suffix` field. You cannot add any hostname and path combinations already configured for another waiting room. Hostnames must belong to the zone that the waiting room is configured on. A single waiting room can be applied to multiple custom hostnames as long as the following is true: * The apex domain is the same between the custom hostnames * Each custom hostname is [configured explicitly](#custom-hostnames) in SSL for SaaS setup. ## Custom hostnames To deploy a waiting room to a custom hostname, the non-wildcard custom hostname must be [configured and active in SSL for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/create-custom-hostnames/). Then, [create](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/) a Waiting Room and optionally apply it to [multiple hostnames](#apply-to-multiple-hostnames-and-paths) with the same apex domain. This means that – if you want a waiting room for `hello.example.com` – `hello.example.com` must be an active custom hostname. You will not be able to create a waiting room at `hello.example.com` based on only `example.com` being set up as a custom hostname, even if you have enabled wildcards for this custom hostname in SSL for SaaS setup. ## Create exceptions to waiting room coverage If there are subpaths or query strings of the path you have configured for your waiting room that you would not like the waiting room to apply to, you can create a [Waiting Room bypass rule](https://developers.cloudflare.com/waiting-room/additional-options/waiting-room-rules/bypass-rules/#common-use-cases) to ensure that traffic is not queued at these parts of your site. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/place-waiting-room/","name":"Place a waiting room"}}]} ``` --- --- title: Access Waiting Room description: Use Cloudflare Waiting Room to create a holding area where users can queue to access a high-traffic area of your enterprise website. For an introduction, refer to the Overview page. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/how-to/waiting-room-dashboard.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Access Waiting Room Use Cloudflare Waiting Room to create a holding area where users can queue to access a high-traffic area of your enterprise website. For an introduction, refer to the [Overview](https://developers.cloudflare.com/waiting-room/) page. To access Waiting Room on the Cloudflare dashboard, go to the **Waiting Room** page. [ Go to **Waiting Room** ](https://dash.cloudflare.com/?to=/:account/:zone/traffic/waiting-rooms) Use the dashboard to [create, edit, update, and delete](https://developers.cloudflare.com/waiting-room/how-to/) waiting rooms. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/how-to/","name":"How to"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/how-to/waiting-room-dashboard/","name":"Access Waiting Room"}}]} ``` --- --- title: Best practices description: Follow these best practices to avoid potential issues and improve the visitor experience. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/reference/best-practices.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Best practices Follow these best practices to avoid potential issues and improve the visitor experience. ## Total active users When specifying the **Total active users** in your [configuration settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/), set the value to `75%` of your origin's traffic capacity. ## Page path When setting the waiting room **Path** in your [configuration settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/), pay attention to potential subpaths. Waiting rooms are enabled on all subpaths, meaning you might be sending more traffic to your waiting room than anticipated. Additionally, if you have multiple waiting rooms, the waiting room with the most specific subpath takes precedence. ## Update during active queueing ### Waiting room template If you want to provide your users with updated information or expectations when they are queueing, Cloudflare recommends that you update your [waiting room template](https://developers.cloudflare.com/waiting-room/how-to/customize-waiting-room/). All changes will be visible to your users in close to real time. ### Configuration settings When users are actively queueing, only make changes to your [configuration settings](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/) when necessary. These changes may impact the estimated wait time shown to end users, which might lead to user confusion. ### Queueing method Though you can change your [queueing method](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/), it may affect users if your waiting room is actively queueing: * **From FIFO to Random**: Users will no longer be ordered based on their cookie timestamp, which may affect the displayed wait time. * **From Random to FIFO**: Users will be ordered based on their cookie timestamp, meaning any new users move to the end of the FIFO queue. Note If you change the queueing method from FIFO > Random > FIFO, users will be ordered by their original entry time. ## Waiting Room and SEO SEO crawlers may end up in a queue during active queueing. When this happens, your sites search results and SEO may be impacted. To avoid this, you can enable SEO Crawler Bypassing from the Waiting Room dashboard or via API. SEO Crawler Bypassing ensures that trusted SEO Crawlers, verified by Bot Management, are never placed in your waiting rooms. By not being queued, SEO crawlers are always able to crawl your site, which helps maintain your SEO and search results in major search engines. By enabling this service, you understand that these verified crawlers are completely bypassing your waiting rooms. No waiting room settings or features will apply to this traffic. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/reference/best-practices/","name":"Best practices"}}]} ``` --- --- title: Configuration settings description: You can customize a variety of options for your waiting rooms. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/reference/configuration-settings.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Configuration settings You can customize a variety of options for your waiting rooms. [ Dashboard settings ](#dashboard-settings) [ Additional details ](#additional-details) ## Dashboard settings | **Settings** | **Notes** | | | | | ------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dashboard Setting** | **API parameter** | **Required?** | **Description** | **Best practices** | | Name | name | Yes | Unique waiting room name. | | | Hostname | host | Yes | Hostname for which the waiting room will be applied (no wildcards). | Do not include http:// or https://. | | Path | path | No | Case-sensitive path of the waiting room. The waiting room will be enabled for all subpaths. Wildcards and query parameters are not supported. | If your server does not allow letter casing, use numbers in your path. | | Additional Hostnames and Paths | additional\_routes | No | Add additional hostnames and/or paths to your waiting room coverage. | Additional hostnames must be within the same zone. Hostname and path combinations must be unique per waiting room. | | Custom Cookie Suffix | cookie\_suffix | Required when using additional\_routes. | Customize the suffix of your waiting room cookie. Suffix will be added to \_cfwaitingroom. | Ensure your cookie name is compliant. Do not change this often. | | Total active users | total\_active\_users | Yes | The maximum number of active sessions allowed in host/path at a given time (must be greater than 200). | Set to 75% of origin traffic capacity and adjust as needed. Adjustments may affect estimated wait time shown to end users. | | New users per minute | new\_users\_per\_minute | Yes | A [threshold](#new-users-per-minute) of users per minute that can be allowed into host/path, greater than 200 and less than or equal to **total active users**. | Set to 100% of peak traffic to ensure users are only queued when necessary | | Session duration | session\_duration | No | The amount of time in minutes (between 1 and 30) that a user who left host/path can come [directly back](#session-duration) without having to go into the waiting room. Defaults to 5 minutes. | | | Session Revocation | | No | Revoke a user's session when they perform a specific action by sending a command to the waiting room using an HTTP header on the response from your origin. | Enable this setting in the dashboard and add the Cf-Waiting-Room-Command: revoke HTTP header to the response from your origin. | | Description | description | No | Description of the waiting room. | | | Disable session renewal | disable\_session\_renewal | No | Only available to Enterprise customers with purchase. If true, users only have session duration minutes to browse your site. If false, a user's session cookie is renewed on every request. | | | JSON response | json\_response\_enabled | No, defaults to false. | Send JSON body when receiving an Accept: application/json header, commonly used with native mobile applications. | Set to true when using a waiting room for non-browser traffic. Follow [this documentation](https://developers.cloudflare.com/waiting-room/how-to/json-response/) for additional steps. | | Queueing status code | queueing\_status\_code | No, defaults 200 (OK). | HTTP status code to be returned while a user is queuing. | | | Turnstile Widget Mode | turnstile\_mode | Yes, defaults invisible. | The type of Turnstile widget to use - refer to the [Turnstile documentation](https://developers.cloudflare.com/turnstile/concepts/widget/#widget-modes) for details. Valid values are off, invisible, visible\_non\_interactive, and visible\_managed. Setting this to off will completely disable the Turnstile integration. | Setting this to invisible makes sense for most rooms, unless you would like end users to be aware the challenge is running. | | Turnstile Fail Action | turnstile\_action | Yes, defaults to log. | The action to take when an end user fails a Turnstile challenge. Valid values are log and infinite\_queue. | Setting this to log makes sense for most rooms, unless you wish to aggressively block bots using an infinite queue. | ## Additional details ### New users per minute When you configure `new users per minute`, this value **is not** the number of users added per minute. Instead, it is the threshold of users allowed per minute (less than or equal to the number of `total active users`). You should set this value at 100% of your expected peak traffic to ensure users are only queued when necessary. ### Session duration Session duration improves user experience in two ways. First, it prevents visitors from having to pass through a waiting room twice for the same transaction. For example, a visitor might want to make a purchase at `example.com`. There's a lot of traffic at `example.com`, so they queue in the waiting room before entering the online store. After a period of time, they leave the waiting room and enter the online store. They make a purchase and leave the online store. However, they forgot to add a note to the order or request a receipt. As long as their [session cookie](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/) is still valid (for the length of time specified by the `session duration`), they can re-enter your application without having to re-queue in the waiting room. Second, session duration lets your waiting room create a dynamic outflow from your application (in addition to dynamic inflow). A user's session cookie expires after a period of inactivity, meaning that new spots can open up as soon as space becomes available and estimated wait times are lower and more accurate. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/reference/configuration-settings/","name":"Configuration settings"}}]} ``` --- --- title: Queueing method description: The queueing method determines the order that visitors exit an active waiting room and reach your application. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/reference/queueing-methods.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Queueing method The **queueing method** determines the order that visitors exit an active waiting room and reach your application. Only certain customers can use queue methods besides First In First Out (FIFO). For more details, refer to [Plans](https://developers.cloudflare.com/waiting-room/plans/) page. Note: Regardless of the queueing method, if `queueAll` is enabled or an event is prequeueing, users in the waiting room will not be accepted to the origin. These users will always get a waiting room page that refreshes automatically. ## First In First Out (FIFO) Your waiting room orders visitors according to when they entered the waiting room. ![First In First Out flow showing visitors entering the origin by order of arrival to the waiting room](https://developers.cloudflare.com/_astro/fifo-queueing-method.CkJk7UcN_HRDnR.webp) Technically, each user receives a [cookie](https://developers.cloudflare.com/waiting-room/reference/waiting-room-cookie/) that contains a timestamp of when their request first hit an actively queueing waiting room. Cloudflare uses that timestamp to order visitors and provide the estimated wait time. Use this method when you want to reward visitors who get in the queue first and wait longer. ## Random When your application has open spots, your waiting room chooses visitors at random to exit the waiting room and enter your application. ![Random queueing flow showing visitors randomly exiting the waiting room and entering an origin](https://developers.cloudflare.com/_astro/random-queueing-method.S1VxQnOu_9YLhG.webp) Use this method when you want to distribute products or services more equitably. Earlier users have a better chance of exiting the waiting room before the estimated wait time because they have more chances to be selected. ## Passthrough Allow all traffic to pass immediately through your waiting room and into your application by setting its `queueing_method` to **passthrough**. Use this setup when you only want to use your waiting room for events — where you can update the queueing method — and otherwise avoid queueing during low-traffic hours. Additionally, you can use this queuing method when you want to gather analytics on your traffic but do not want to queue any users. With passthrough on, all traffic will be sent directly to your origin. However, analytics will be gathered on `total active users`, `new users per minute` and `time on origin`. We recommend this as a useful test to gather insights into your traffic patterns to help determine appropriate threshold settings. ## Reject Prevent any traffic from reaching your application by setting its `queueing_method` to **reject**. Users will get a static page. Use this setup for event-only endpoints or to perform application maintenance. ## Change queueing methods Though you can change your [queueing method](https://developers.cloudflare.com/waiting-room/reference/queueing-methods/), it may affect users if your waiting room is actively queueing: * **From FIFO to Random**: Users will no longer be ordered based on their cookie timestamp, which may affect the displayed wait time. * **From Random to FIFO**: Users will be ordered based on their cookie timestamp, meaning any new users move to the end of the FIFO queue. Note If you change the queueing method from FIFO > Random > FIFO, users will be ordered by their original entry time. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/reference/queueing-methods/","name":"Queueing method"}}]} ``` --- --- title: API commands description: Cloudflare Waiting Room redirect visitors to virtual waiting rooms when they are trying to access web pages that have high volumes of traffic. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/reference/waiting-room-api.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # API commands Cloudflare Waiting Room redirect visitors to virtual waiting rooms when they are trying to access web pages that have high volumes of traffic. The [Cloudflare Waiting Room API](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/list/) provides an interface for programmatically managing waiting rooms. ## Request URL format To invoke a [Cloudflare Waiting Room API](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/list/) operation, append the endpoint to the Cloudflare API base URL: Terminal window ``` https://api.cloudflare.com/client/v4 ``` For authentication instructions, refer to [Getting Started: Requests](https://developers.cloudflare.com/fundamentals/api/) in the Cloudflare API documentation. For help with endpoints and pagination, refer to [Getting Started: Endpoints](https://developers.cloudflare.com/fundamentals/api/). ## Manage your waiting room | Operation | Method + URL stub | Notes | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ---------------------------------- | | [List waiting rooms](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/list/) | GET zones/{:zone\_identifier}/waiting\_rooms | List all waiting rooms for a zone. | | [Create waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/create/) | POST zones/{:zone\_identifier}/waiting\_rooms | Create a waiting room. | | [Waiting room details](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/get/) | GET zones/{:zone\_identifier}/waiting\_rooms/{:identifier} | Fetch a waiting room. | | [Update waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/update/) | PUT zones/{:zone\_identifier}/waiting\_rooms/{:identifier} | Update a waiting room. | | [Delete waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/delete/) | DELETE zones/{:zone\_identifier}/waiting\_rooms/{:identifier} | Delete a waiting room. | | [Patch waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/methods/edit/) | PATCH zones/{:zone\_identifier}/waiting\_rooms/{:identifier} | Patch a configured waiting room. | ## Fetch the current status of a waiting room | Operation | Method + URL stub | Notes | | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Get the current status of a waiting room](https://developers.cloudflare.com/api/resources/waiting%5Frooms/subresources/statuses/methods/get/) | GET zones/{:zone\_identifier}/waiting\_rooms/{:identifier}/status | Returns queueing if the queue is activated (clients are put in the waiting room).Returns not\_queueing if the queue is not activated or if the waiting room is suspended. | ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/reference/waiting-room-api/","name":"API commands"}}]} ``` --- --- title: Cookies description: A waiting room only uses the __cfwaitingroom cookie when a visitor requests access to a host and path combination with an enabled and associated waiting room. When the waiting room is suspended, traffic goes to the origin and the __cfwaitingroom cookie is not created. The __cfwaitingroom cookie is encrypted to prevent modification by users. You may append a custom suffix to your waiting room cookie to customize the name of your waiting room cookie. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/waiting-room/reference/waiting-room-cookie.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Cookies A waiting room only uses the `__cfwaitingroom` cookie when a visitor requests access to a host and path combination with an enabled and associated waiting room. When the waiting room is suspended, traffic goes to the origin and the `__cfwaitingroom` cookie is not created. The `__cfwaitingroom` cookie is encrypted to prevent modification by users. You may append a [custom suffix](#customize-cookie-name) to your waiting room cookie to customize the name of your waiting room cookie. Important: Cloudflare Waiting Room requires the `__cfwaitingroom` cookie. When a waiting room is actively queueing, users cannot visit that host and path combination without enabling cookies. ## Cookie function The `__cfwaitingroom` cookie is used to: * Track a user's position in the waiting room queue and serve them in the correct order. * Monitor each visitor's duration in the application to provide an [accurate entry time](#estimated-wait-time-fifo-queueing-method) to visitors queueing in the waiting room. * To allow re-entry for a period of time (specified by [session\_duration](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/#session-duration)) without going back in the waiting room. ## Cookie expiration time * While a visitor stays in a waiting room, `__cfwaitingroom` cookie expiration is always set to five minutes, but renews every 20 seconds automatically as long as the visitor does not close the tab or leaves your application. * When the visitor accesses the application, the `__cfwaitingroom` cookie expires after an interval (specified by [session\_duration](https://developers.cloudflare.com/waiting-room/reference/configuration-settings/#session-duration)). ## Customize cookie name You can customize the name of your waiting room cookie by adding a custom suffix to the end of `__cfwaitingroom`. To do this via the UI, complete the Custom cookie field in the [Create](https://developers.cloudflare.com/waiting-room/how-to/create-waiting-room/) or [Edit](https://developers.cloudflare.com/waiting-room/how-to/edit-delete-waiting-room/) workflow. To do this via the API, enter a value for `cookie_suffix` when creating or editing a waiting room. The cookie suffix is a required field when [using additional hostnames](https://developers.cloudflare.com/waiting-room/how-to/place-waiting-room/) and paths for a single waiting room. Ensure your cookie is compliant with any applicable policies. ## Estimated wait time (FIFO queueing method) When a visitor first enters the host and path combination for your waiting room, they receive the `__cfwaitingroom` cookie. That cookie contains a unique group ID, which corresponds to the minute your visitor entered the waiting room. Using this value, we can tell how many visitors are in front of a specific group. Each cookie also contains a value for `acceptedAt`, which corresponds to the minute your visitor entered your application. This value lets us know how many visitors per minute are leaving the waiting room to enter your application. ``` visitorsAhead ÷ activeUsersToWebApplication = estimatedWaitTime ``` We combine these pieces of information to calculate estimated wait time for each group of visitors. For more details about the technical implementation of Cloudflare Waiting Room, refer to the [blog post ↗](https://blog.cloudflare.com/building-waiting-room-on-workers-and-durable-objects/). ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waiting-room/","name":"Waiting Room"}},{"@type":"ListItem","position":3,"item":{"@id":"/waiting-room/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/waiting-room/reference/waiting-room-cookie/","name":"Cookies"}}]} ```