Measuring queue wait times using the Custom Queues API

In this article, you’ll use the Queue Events endpoint to calculate the maximum and average time work items spend waiting in an omnichannel queue before they’re processed.

What you need

• A Zendesk account with admin access.
• One of the following plans:
  • Zendesk Suite: Professional, Enterprise, or Enterprise Plus
  • Zendesk Support: Professional or Enterprise
• Omnichannel routing turned on with at least one custom queue
• API authentication configured for your Zendesk account (such as an API token)

About the Queue Events endpoint

The /api/v2/queue_events endpoint returns event-level records related to work items entering and leaving queues across Messaging, Talk, and Support.

Queue events are retained for the past 90 days only.

Filtering results

The table below shows the request query parameters you can use to filter queue events to calculate queue wait times. For the full list of supported parameters and returned fields, see Queue Events.

Field	Description
channel	Filter by channel. Valid values are: "MESSAGING", "TALK", and "SUPPORT"
event_type	Type of work item change event
queue_id	Identifier to group or filter by a specific queue
start_time	Start of the time window to return events, specified as Unix epoch time in seconds
end_time	End of the time window to return events, specified as Unix epoch time in seconds

All timestamp fields and time-based parameters are in UTC ISO 8601 format.

To measure queue wait times, you'll:

1. Fetch the raw data
2. Calculate the wait time per event
3. Calculate the metrics

Fetching the raw data

First, call /api/v2/queue_events for your time window, optionally filtering by queue_id and channel.

After retrieving the events, select the records that represent work items leaving the queue (for example, events where event_type is "OUTBOUND", if that value represents leave-queue events in your account). To calculate wait time, keep only records that include both start_queue_time and end_queue_time, since these fields are required to compute the time a work item spent waiting in the queue.

Depending on your workflow, you can also use fields such as outbound_reason to further narrow results to work items that were accepted or otherwise moved out of the queue.

Example request:

curl -G 'https://{subdomain}.zendesk.com/api/v2/queue_events' \
  --data-urlencode "channel=MESSAGING" \
  --data-urlencode "queue_id={queue_id}" \
  --data-urlencode "start_time={start_time}" \
  --data-urlencode "end_time={end_time}" \
  -v -u "{email_address}/token:{api_token}"

Example response (truncated):

{
  "queue_data": [
    {
      "queue_event_id": "evt_a333",
      "queue_id": "01KXKC6EZ93E7EPHSF1000001",
      "channel": "MESSAGING",
      "event_type": "OUTBOUND",
      "outbound_reason": "ACCEPTED",
      "event_occurred_at": "2024-06-10T09:30:00Z",
      "start_queue_time": "2024-06-10T09:15:00Z",
      "end_queue_time": "2024-06-10T09:30:00Z"
    }
  ]
}

Calculating the wait time per event

Next, for each returned event, calculate the wait time using the following formula:

wait time (seconds) = end_queue_time − start_queue_time

Where:

• start_queue_time is the time when the work item entered or started waiting in the queue
• end_queue_time is the time when the work item left the queue (was accepted, routed onward, and so forth)

Example:

• start_queue_time: 2024-06-10T09:15:00Z
• end_queue_time: 2024-06-10T09:30:00Z

The calculated wait time is 15 minutes or 900 seconds.

Calculating the metrics

After you’ve calculated a wait time for each event, aggregate the results into the metrics you need:

• Overall (all queues and channels): Compute the average wait time (mean of all event wait times) and the maximum wait time (largest observed value).
• Daily: Group by the date portion of event_occurred_at (for example, YYYY-MM-DD), then compute the daily average and daily maximum wait time.
• Per queue: Group by queue_id, then compute average and maximum wait time for each queue.
• Per channel within a queue: Filter to a specific queue_id, group by channel, and compute average and maximum wait time per channel within that queue.