events

Creates, updates, deletes, gets or lists an events resource.

Overview

Name	events
Type	Resource
Id	cloudflare.waiting_rooms.events

Fields

The following fields are returned by SELECT queries:

get

Event details response

Name	Datatype	Description
result	object

list

List events response

Name	Datatype	Description
id	string	(example: 25756b2dfe6e378a06b033b670413757)
name	string	A unique name to identify the event. Only alphanumeric characters, hyphens and underscores are allowed. (example: production_webinar_event)
created_on	string (date-time)	(example: 2014-01-01T05:20:00.12345Z)
custom_page_html	string	If set, the event will override the waiting room's custom_page_html property while it is active. If null, the event will inherit it. (example: {{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}})
description	string	A note that you can use to add more details about the event. (default: , example: Production event - DO NOT MODIFY)
disable_session_renewal	boolean	If set, the event will override the waiting room's disable_session_renewal property while it is active. If null, the event will inherit it.
event_end_time	string	An ISO 8601 timestamp that marks the end of the event. (example: 2021-09-28T17:00:00.000Z)
event_start_time	string	An ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. The start time must be at least one minute before event_end_time. (example: 2021-09-28T15:30:00.000Z)
modified_on	string (date-time)	(example: 2014-01-01T05:20:00.12345Z)
new_users_per_minute	integer	If set, the event will override the waiting room's new_users_per_minute property while it is active. If null, the event will inherit it. This can only be set if the event's total_active_users property is also set.
prequeue_start_time	string	An ISO 8601 timestamp that marks when to begin queueing all users before the event starts. The prequeue must start at least five minutes before event_start_time. (example: 2021-09-28T15:00:00.000Z)
queueing_method	string	If set, the event will override the waiting room's queueing_method property while it is active. If null, the event will inherit it. (example: random)
session_duration	integer	If set, the event will override the waiting room's session_duration property while it is active. If null, the event will inherit it.
shuffle_at_event_start	boolean	If enabled, users in the prequeue will be shuffled randomly at the event_start_time. Requires that prequeue_start_time is not null. This is useful for situations when many users will join the event prequeue at the same time and you want to shuffle them to ensure fairness. Naturally, it makes the most sense to enable this feature when the queueing_method during the event respects ordering such as fifo, or else the shuffling may be unnecessary.
suspended	boolean	Suspends or allows an event. If set to true, the event is ignored and traffic will be handled based on the waiting room configuration.
total_active_users	integer	If set, the event will override the waiting room's total_active_users property while it is active. If null, the event will inherit it. This can only be set if the event's new_users_per_minute property is also set.
turnstile_action	string	If set, the event will override the waiting room's turnstile_action property while it is active. If null, the event will inherit it. (log, infinite_queue)
turnstile_mode	string	If set, the event will override the waiting room's turnstile_mode property while it is active. If null, the event will inherit it. (off, invisible, visible_non_interactive, visible_managed)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	event_id, waiting_room_id, zone_id		Fetches a single configured event for a waiting room.
list	select	waiting_room_id, zone_id	page, per_page	Lists events for a waiting room.
create	insert	waiting_room_id, zone_id, name, event_start_time, event_end_time		Only available for the Waiting Room Advanced subscription. Creates an event for a waiting room. An event takes place during a specified period of time, temporarily changing the behavior of a waiting room. While the event is active, some of the properties in the event's configuration may either override or inherit from the waiting room's configuration. Note that events cannot overlap with each other, so only one event can be active at a time.
edit	update	event_id, waiting_room_id, zone_id, name, event_start_time, event_end_time		Patches a configured event for a waiting room.
update	replace	event_id, waiting_room_id, zone_id, name, event_start_time, event_end_time		Updates a configured event for a waiting room.
delete	delete	event_id, waiting_room_id, zone_id		Deletes an event for a waiting room.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
event_id	string	The event ID.
waiting_room_id	string	The Waiting Room ID.
zone_id	string	The Cloudflare zone ID.
page	number	Page number of paginated results.
per_page	number	Maximum number of results per page. Must be a multiple of 5.

SELECT examples

get

Fetches a single configured event for a waiting room.

SELECT
result
FROM cloudflare.waiting_rooms.events
WHERE event_id = '{{ event_id }}' -- required
AND waiting_room_id = '{{ waiting_room_id }}' -- required
AND zone_id = '{{ zone_id }}' -- required
;

list

Lists events for a waiting room.

SELECT
id,
name,
created_on,
custom_page_html,
description,
disable_session_renewal,
event_end_time,
event_start_time,
modified_on,
new_users_per_minute,
prequeue_start_time,
queueing_method,
session_duration,
shuffle_at_event_start,
suspended,
total_active_users,
turnstile_action,
turnstile_mode
FROM cloudflare.waiting_rooms.events
WHERE waiting_room_id = '{{ waiting_room_id }}' -- required
AND zone_id = '{{ zone_id }}' -- required
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
;

INSERT examples

create

Only available for the Waiting Room Advanced subscription. Creates an event for a waiting room. An event takes place during a specified period of time, temporarily changing the behavior of a waiting room. While the event is active, some of the properties in the event's configuration may either override or inherit from the waiting room's configuration. Note that events cannot overlap with each other, so only one event can be active at a time.

INSERT INTO cloudflare.waiting_rooms.events (
custom_page_html,
description,
disable_session_renewal,
event_end_time,
event_start_time,
name,
new_users_per_minute,
prequeue_start_time,
queueing_method,
session_duration,
shuffle_at_event_start,
suspended,
total_active_users,
turnstile_action,
turnstile_mode,
waiting_room_id,
zone_id
)
SELECT 
'{{ custom_page_html }}',
'{{ description }}',
{{ disable_session_renewal }},
'{{ event_end_time }}' /* required */,
'{{ event_start_time }}' /* required */,
'{{ name }}' /* required */,
{{ new_users_per_minute }},
'{{ prequeue_start_time }}',
'{{ queueing_method }}',
{{ session_duration }},
{{ shuffle_at_event_start }},
{{ suspended }},
{{ total_active_users }},
'{{ turnstile_action }}',
'{{ turnstile_mode }}',
'{{ waiting_room_id }}',
'{{ zone_id }}'
RETURNING
result
;

Manifest

# Description fields are for documentation purposes
- name: events
props:
  - name: waiting_room_id
    value: "{{ waiting_room_id }}"
    description: Required parameter for the events resource.
  - name: zone_id
    value: "{{ zone_id }}"
    description: Required parameter for the events resource.
  - name: custom_page_html
    value: "{{ custom_page_html }}"
    description: |
      If set, the event will override the waiting room's `custom_page_html` property while it is active. If null, the event will inherit it.
  - name: description
    value: "{{ description }}"
    description: |
      A note that you can use to add more details about the event.
    default: 
  - name: disable_session_renewal
    value: {{ disable_session_renewal }}
    description: |
      If set, the event will override the waiting room's `disable_session_renewal` property while it is active. If null, the event will inherit it.
  - name: event_end_time
    value: "{{ event_end_time }}"
    description: |
      An ISO 8601 timestamp that marks the end of the event.
  - name: event_start_time
    value: "{{ event_start_time }}"
    description: |
      An ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. The start time must be at least one minute before `event_end_time`.
  - name: name
    value: "{{ name }}"
    description: |
      A unique name to identify the event. Only alphanumeric characters, hyphens and underscores are allowed.
  - name: new_users_per_minute
    value: {{ new_users_per_minute }}
    description: |
      If set, the event will override the waiting room's `new_users_per_minute` property while it is active. If null, the event will inherit it. This can only be set if the event's `total_active_users` property is also set.
  - name: prequeue_start_time
    value: "{{ prequeue_start_time }}"
    description: |
      An ISO 8601 timestamp that marks when to begin queueing all users before the event starts. The prequeue must start at least five minutes before `event_start_time`.
  - name: queueing_method
    value: "{{ queueing_method }}"
    description: |
      If set, the event will override the waiting room's `queueing_method` property while it is active. If null, the event will inherit it.
  - name: session_duration
    value: {{ session_duration }}
    description: |
      If set, the event will override the waiting room's `session_duration` property while it is active. If null, the event will inherit it.
  - name: shuffle_at_event_start
    value: {{ shuffle_at_event_start }}
    description: |
      If enabled, users in the prequeue will be shuffled randomly at the `event_start_time`. Requires that `prequeue_start_time` is not null. This is useful for situations when many users will join the event prequeue at the same time and you want to shuffle them to ensure fairness. Naturally, it makes the most sense to enable this feature when the `queueing_method` during the event respects ordering such as **fifo**, or else the shuffling may be unnecessary.
    default: false
  - name: suspended
    value: {{ suspended }}
    description: |
      Suspends or allows an event. If set to `true`, the event is ignored and traffic will be handled based on the waiting room configuration.
    default: false
  - name: total_active_users
    value: {{ total_active_users }}
    description: |
      If set, the event will override the waiting room's `total_active_users` property while it is active. If null, the event will inherit it. This can only be set if the event's `new_users_per_minute` property is also set.
  - name: turnstile_action
    value: "{{ turnstile_action }}"
    description: |
      If set, the event will override the waiting room's `turnstile_action` property while it is active. If null, the event will inherit it.
    valid_values: ['log', 'infinite_queue']
  - name: turnstile_mode
    value: "{{ turnstile_mode }}"
    description: |
      If set, the event will override the waiting room's `turnstile_mode` property while it is active. If null, the event will inherit it.
    valid_values: ['off', 'invisible', 'visible_non_interactive', 'visible_managed']

UPDATE examples

edit

Patches a configured event for a waiting room.

UPDATE cloudflare.waiting_rooms.events
SET 
custom_page_html = '{{ custom_page_html }}',
description = '{{ description }}',
disable_session_renewal = {{ disable_session_renewal }},
event_end_time = '{{ event_end_time }}',
event_start_time = '{{ event_start_time }}',
name = '{{ name }}',
new_users_per_minute = {{ new_users_per_minute }},
prequeue_start_time = '{{ prequeue_start_time }}',
queueing_method = '{{ queueing_method }}',
session_duration = {{ session_duration }},
shuffle_at_event_start = {{ shuffle_at_event_start }},
suspended = {{ suspended }},
total_active_users = {{ total_active_users }},
turnstile_action = '{{ turnstile_action }}',
turnstile_mode = '{{ turnstile_mode }}'
WHERE 
event_id = '{{ event_id }}' --required
AND waiting_room_id = '{{ waiting_room_id }}' --required
AND zone_id = '{{ zone_id }}' --required
AND name = '{{ name }}' --required
AND event_start_time = '{{ event_start_time }}' --required
AND event_end_time = '{{ event_end_time }}' --required
RETURNING
result;

REPLACE examples

update

Updates a configured event for a waiting room.

REPLACE cloudflare.waiting_rooms.events
SET 
custom_page_html = '{{ custom_page_html }}',
description = '{{ description }}',
disable_session_renewal = {{ disable_session_renewal }},
event_end_time = '{{ event_end_time }}',
event_start_time = '{{ event_start_time }}',
name = '{{ name }}',
new_users_per_minute = {{ new_users_per_minute }},
prequeue_start_time = '{{ prequeue_start_time }}',
queueing_method = '{{ queueing_method }}',
session_duration = {{ session_duration }},
shuffle_at_event_start = {{ shuffle_at_event_start }},
suspended = {{ suspended }},
total_active_users = {{ total_active_users }},
turnstile_action = '{{ turnstile_action }}',
turnstile_mode = '{{ turnstile_mode }}'
WHERE 
event_id = '{{ event_id }}' --required
AND waiting_room_id = '{{ waiting_room_id }}' --required
AND zone_id = '{{ zone_id }}' --required
AND name = '{{ name }}' --required
AND event_start_time = '{{ event_start_time }}' --required
AND event_end_time = '{{ event_end_time }}' --required
RETURNING
result;

DELETE examples

delete

Deletes an event for a waiting room.

DELETE FROM cloudflare.waiting_rooms.events
WHERE event_id = '{{ event_id }}' --required
AND waiting_room_id = '{{ waiting_room_id }}' --required
AND zone_id = '{{ zone_id }}' --required
;