REST API: TaskQueue Statistics
TaskRouter provides real time and historical statistics for TaskQueues. Historical statistics allow you to analyze data from the past 30 days.
Twilio offers the following APIs for TaskQueue statistics:
TaskQueue RealTime Statistics
If you are only concerned with the real time statistics of your TaskQueue, you can utilize the below endpoint.
We recommended leveraging caching when utilizing this endpoint from your backend application to ensure this endpoint can support your scaling needs.
In scenarios where this endpoint would be used from a client application, we recommend implementing a sync layer, e.g., via Twilio Sync, to help synchronize this endpoint’s state across all clients, and to ensure this endpoint can scale with your user growth.
Resource URI
GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/RealTimeStatistics
Parameters in REST API format  

workspace_sid
Path

The SID of the Workspace with the TaskQueue to fetch. 
task_queue_sid
Path

The SID of the TaskQueue for which to fetch statistics. 
task_channel
Optional

The TaskChannel for which to fetch statistics. Can be the TaskChannel's SID or its 
Real time statistics relating to a TaskQueue include the following:
Resource Properties in REST API format  

account_sid

The SID of the Account that created the TaskQueue resource. 
activity_statistics

The number of current Workers by Activity. 
longest_task_waiting_age

The age of the longest waiting Task. 
longest_task_waiting_sid

The SID of the longest waiting Task. 
longest_relative_task_age_in_queue

The relative age in the TaskQueue for the longest waiting Task. Calculation is based on the time when the Task entered the TaskQueue. 
longest_relative_task_sid_in_queue

The Task SID of the Task waiting in the TaskQueue the longest. Calculation is based on the time when the Task entered the TaskQueue. 
task_queue_sid

The SID of the TaskQueue from which these statistics were calculated. 
tasks_by_priority

The number of Tasks by priority. For example: 
tasks_by_status

The number of Tasks by their current status. For example: 
total_available_workers

The total number of Workers available for Tasks in the TaskQueue. 
total_eligible_workers

The total number of Workers eligible for Tasks in the TaskQueue, independent of their Activity state. 
total_tasks

The total number of Tasks. 
workspace_sid

The SID of the Workspace that contains the TaskQueue. 
url

The absolute URL of the TaskQueue statistics resource. 
Bulk retrieval of TaskQueue RealTime Statistics
To retrieve realtime statistics for multiple queues, you can utilize the below endpoint.
Resource URI
POST /v1/Workspaces/{WorkspaceSid}/TaskQueues/RealTimeStatistics
Parameters in REST API format  

workspace_sid
Path

The unique SID identifier of the Workspace. 
POST Parameters
Field  Required?  Description 

QueueSids  Yes  String array where each string represents one TaskQueueSID. (🏢 Not PII ) 
Real time statistics for TaskQueueSIDs provided as POST parameter include the following:
Resource Properties in REST API format  

account_sid

The SID of the Account that created the TaskQueue resource. 
workspace_sid

The SID of the Workspace that contains the TaskQueue. 
task_queue_data

The realtime statistics for each requested TaskQueue SID.

task_queue_response_count

The number of TaskQueue statistics received in task_queue_data. 
url

The absolute URL of the TaskQueue statistics resource. 
Validation
The request body is validated for the following conditions:
 If the number of TaskQueueSIDs in the request body is less than 1 or exceeds 50, an HTTP 400 error is returned.
 If the request body contains invalid TaskQueueSIDs, an HTTP 400 error is returned.
 If the request body includes valid TaskQueueSIDs that are not part of this account, these TaskQueueSIDs are included in the response but with zero values for all statistics.
 This Bulk Retrieval API has a rate limit of 5 requeests per second. If this rate limit is exceeded, an HTTP 429 error is returned.
TaskQueue Cumulative Statistics
If you are only concerned with the cumulative statistics over a certain time period, you can utilize the below endpoint. Cumulative statistics allow you to analyze data from the past 30 days.
Resource URI
GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/CumulativeStatistics
Parameters in REST API format  

workspace_sid
Path

The SID of the Workspace with the TaskQueue to fetch. 
task_queue_sid
Path

The SID of the TaskQueue for which to fetch statistics. 
end_date
Optional

Only calculate statistics from this date and time and earlier, specified in GMT as an ISO 8601 datetime. 
minutes
Optional

Only calculate statistics since this many minutes in the past. The default is 15 minutes. 
start_date
Optional

Only calculate statistics from this date and time and later, specified in ISO 8601 format. 
task_channel
Optional

Only calculate cumulative statistics on this TaskChannel. Can be the TaskChannel's SID or its 
split_by_wait_time
Optional

A comma separated list of values that describes the thresholds, in seconds, to calculate statistics on. For each threshold specified, the number of Tasks canceled and reservations accepted above and below the specified thresholds in seconds are computed. TaskRouter will calculate statistics on up to 10,000 Tasks/Reservations for any given threshold. 
Cumulative statistics relating to a TaskQueue include the following over the interval:
Resource Properties in REST API format  

account_sid

The SID of the Account that created the TaskQueue resource. 
avg_task_acceptance_time

The average time in seconds between Task creation and acceptance. 
start_time

The beginning of the interval during which these statistics were calculated, in ISO 8601 format. 
end_time

The end of the interval during which these statistics were calculated, in ISO 8601 format. 
reservations_created

The total number of Reservations created for Tasks in the TaskQueue. 
reservations_accepted

The total number of Reservations accepted for Tasks in the TaskQueue. 
reservations_rejected

The total number of Reservations rejected for Tasks in the TaskQueue. 
reservations_timed_out

The total number of Reservations that timed out for Tasks in the TaskQueue. 
reservations_canceled

The total number of Reservations canceled for Tasks in the TaskQueue. 
reservations_rescinded

The total number of Reservations rescinded. 
split_by_wait_time

A list of objects that describe the number of Tasks canceled and reservations accepted above and below the thresholds specified in seconds. 
task_queue_sid

The SID of the TaskQueue from which these statistics were calculated. 
wait_duration_until_accepted

The wait duration statistics ( 
wait_duration_until_canceled

The wait duration statistics ( 
wait_duration_in_queue_until_accepted

The relative wait duration statistics ( 
tasks_canceled

The total number of Tasks canceled in the TaskQueue. 
tasks_completed

The total number of Tasks completed in the TaskQueue. 
tasks_deleted

The total number of Tasks deleted in the TaskQueue. 
tasks_entered

The total number of Tasks entered into the TaskQueue. 
tasks_moved

The total number of Tasks that were moved from one queue to another. 
workspace_sid

The SID of the Workspace that contains the TaskQueue. 
url

The absolute URL of the TaskQueue statistics resource. 
TaskQueue Instance Statistics
Resource URI
GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/Statistics
Parameters in REST API format  

workspace_sid
Path

The SID of the Workspace with the TaskQueue to fetch. 
task_queue_sid
Path

The SID of the TaskQueue for which to fetch statistics. 
end_date
Optional

Only calculate statistics from this date and time and earlier, specified in GMT as an ISO 8601 datetime. 
minutes
Optional

Only calculate statistics since this many minutes in the past. The default is 15 minutes. 
start_date
Optional

Only calculate statistics from this date and time and later, specified in ISO 8601 format. 
task_channel
Optional

Only calculate realtime and cumulative statistics for the specified TaskChannel. Can be the TaskChannel's SID or its 
split_by_wait_time
Optional

A comma separated list of values that describes the thresholds, in seconds, to calculate statistics on. For each threshold specified, the number of Tasks canceled and reservations accepted above and below the specified thresholds in seconds are computed. 
Minutes
cannot be used in combination with StartDate
and EndDate
parameters. If no parameters are passed, 15 minutes will be the default.
Resource Properties in REST API format  

account_sid

The SID of the Account that created the TaskQueue resource. 
cumulative

An object that contains the cumulative statistics for the TaskQueue. 
realtime

An object that contains the realtime statistics for the TaskQueue. 
task_queue_sid

The SID of the TaskQueue from which these statistics were calculated. 
workspace_sid

The SID of the Workspace that contains the TaskQueue. 
url

The absolute URL of the TaskQueue statistics resource. 
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.