Measuring queue size using the Custom Queues API

In this article, you’ll use the Queue Events endpoint to calculate minimum, maximum, and average queue size for an omnichannel queue. You can then use these results in your own reporting tools.

Queue size represents the number of work items waiting in a queue at a given point in time. Tracking minimum, maximum, and average queue size (overall, daily, per queue, and per channel) can help you understand workload patterns and make better staffing and routing decisions.

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 provides 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 size metrics. 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"
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 size, you'll:

1. Fetch the raw data
2. Calculate the minimum and maximum queue size
3. Calculate the average queue size

Fetching the raw data

First, call /api/v2/queue_events to retrieve events for your period of interest. You can optionally filter by queue_id to focus on a specific queue and by channel to segment results by messaging, talk, or support. Use start_time and end_time to define the time window you want to measure.

Example request:

curl -G 'https://{subdomain}.zendesk.com/api/v2/queue_events' \
  --data-urlencode "channel=MESSAGING" \
  --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_occurred_at": "2024-06-10T09:30:00Z",
      "current_channel_queue_size": 4,
      "hourly_channel_queue_size_seconds": 17
    }
  ]
}

The response includes current_channel_queue_size, which you’ll use to calculate minimum and maximum queue size.

Calculating minimum and maximum queue size

To calculate minimum and maximum queue size, use current_channel_queue_size from each event and compute the smallest and largest values in your filtered dataset. event_occurred_at is returned in each event and can be used for time-based grouping, such as daily rollups.

You can calculate these metrics for:

• The overall dataset
• Daily, grouped by the date portion of event_occurred_at
• Each queue, grouped by queue_id
• Each channel within a queue, grouped by queue_id and channel

Calculating average queue size

To calculate the average queue size over a time period, you should first convert each hour’s hourly_channel_queue_size_seconds into an hourly average queue size, and then average those hourly values across the time period.

First, calculate the hourly average. For each hour in your timeframe:

Hourly average queue size = hourly_channel_queue_size_seconds divided by 3600

This converts “queue-size-seconds accumulated during the hour” into the average number of items in the queue during that hour.

Daily average (full day)

1. Compute the hourly average for each of the 24 hours in the day (hourly_channel_queue_size_seconds divided by 3600).
2. Sum the 24 hourly averages.
3. Divide by 24.

Or, daily average = (sum of hourly averages for the day) divided by 24

Weekly average (full week)

1. Compute the daily average for each day in the week (using the daily method above).
2. Sum the 7 daily averages.
3. Divide by 7.

Or, weekly average = (sum of daily averages for the week) divided by 7