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:
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.
_10GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/RealTimeStatistics
WorkspaceSid
type: SID<WS>The SID of the Workspace with the TaskQueue to fetch.
^WS[0-9a-fA-F]{32}$
34
34
TaskQueueSid
type: SID<WQ>The SID of the TaskQueue for which to fetch statistics.
^WQ[0-9a-fA-F]{32}$
34
34
TaskChannel
type: stringThe TaskChannel for which to fetch statistics. Can be the TaskChannel's SID or its unique_name
, such as voice
, sms
, or default
.
Real time statistics relating to a TaskQueue include the following:
account_sid
type: SID<AC>The SID of the Account that created the TaskQueue resource.
^AC[0-9a-fA-F]{32}$
34
34
longest_task_waiting_sid
type: SID<WT>The SID of the longest waiting Task.
^WT[0-9a-fA-F]{32}$
34
34
longest_relative_task_age_in_queue
type: integerThe 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
type: SID<WT>The Task SID of the Task waiting in the TaskQueue the longest. Calculation is based on the time when the Task entered the TaskQueue.
^WT[0-9a-fA-F]{32}$
34
34
task_queue_sid
type: SID<WQ>The SID of the TaskQueue from which these statistics were calculated.
^WQ[0-9a-fA-F]{32}$
34
34
tasks_by_priority
type: objectThe number of Tasks by priority. For example: {"0": "10", "99": "5"}
shows 10 Tasks at priority 0 and 5 at priority 99.
tasks_by_status
type: objectThe number of Tasks by their current status. For example: {"pending": "1", "reserved": "3", "assigned": "2", "completed": "5"}
.
total_available_workers
type: integerThe total number of Workers available for Tasks in the TaskQueue.
total_eligible_workers
type: integerThe total number of Workers eligible for Tasks in the TaskQueue, independent of their Activity state.
workspace_sid
type: SID<WS>The SID of the Workspace that contains the TaskQueue.
^WS[0-9a-fA-F]{32}$
34
34
To retrieve real-time statistics for multiple queues, you can utilize the below endpoint.
_10POST /v1/Workspaces/{WorkspaceSid}/TaskQueues/RealTimeStatistics
Uri Parameters |
---|
WorkspaceSidPOST SID<WS> NOT PII The unique SID identifier of the Workspace. |
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:
account_sid
type: SID<AC>The SID of the Account that created the TaskQueue resource.
^AC[0-9a-fA-F]{32}$
34
34
workspace_sid
type: SID<WS>The SID of the Workspace that contains the TaskQueue.
^WS[0-9a-fA-F]{32}$
34
34
task_queue_data
type: arrayThe real-time statistics for each requested TaskQueue SID. task_queue_data
returns the following attributes:
task_queue_sid
: The SID of the TaskQueue from which these statistics were calculated.
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, regardless of their Activity state.
total_tasks
: The total number of Tasks.
longest_task_waiting_age
: The age of the longest waiting Task.
longest_task_waiting_sid
: The SID of the longest waiting Task.
tasks_by_status
: The number of Tasks grouped by their current status.
tasks_by_priority
: The number of Tasks grouped by priority.
activity_statistics
: The number of current Workers grouped by Activity.
task_queue_response_count
type: integerThe number of TaskQueue statistics received in task_queue_data.
The request body is validated for the following conditions:
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.
_10GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/CumulativeStatistics
WorkspaceSid
type: SID<WS>The SID of the Workspace with the TaskQueue to fetch.
^WS[0-9a-fA-F]{32}$
34
34
TaskQueueSid
type: SID<WQ>The SID of the TaskQueue for which to fetch statistics.
^WQ[0-9a-fA-F]{32}$
34
34
EndDate
type: string<date-time>Only calculate statistics from this date and time and earlier, specified in GMT as an ISO 8601 date-time.
Minutes
type: integerOnly calculate statistics since this many minutes in the past. The default is 15 minutes.
StartDate
type: string<date-time>Only calculate statistics from this date and time and later, specified in ISO 8601 format.
TaskChannel
type: stringOnly calculate cumulative statistics on this TaskChannel. Can be the TaskChannel's SID or its unique_name
, such as voice
, sms
, or default
.
SplitByWaitTime
type: stringA 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:
account_sid
type: SID<AC>The SID of the Account that created the TaskQueue resource.
^AC[0-9a-fA-F]{32}$
34
34
avg_task_acceptance_time
type: integerThe average time in seconds between Task creation and acceptance.
start_time
type: string<date-time>The beginning of the interval during which these statistics were calculated, in ISO 8601 format.
end_time
type: string<date-time>The end of the interval during which these statistics were calculated, in ISO 8601 format.
reservations_created
type: integerThe total number of Reservations created for Tasks in the TaskQueue.
reservations_accepted
type: integerThe total number of Reservations accepted for Tasks in the TaskQueue.
reservations_rejected
type: integerThe total number of Reservations rejected for Tasks in the TaskQueue.
reservations_timed_out
type: integerThe total number of Reservations that timed out for Tasks in the TaskQueue.
reservations_canceled
type: integerThe total number of Reservations canceled for Tasks in the TaskQueue.
split_by_wait_time
type: objectA list of objects that describe the number of Tasks canceled and reservations accepted above and below the thresholds specified in seconds.
task_queue_sid
type: SID<WQ>The SID of the TaskQueue from which these statistics were calculated.
^WQ[0-9a-fA-F]{32}$
34
34
wait_duration_until_accepted
type: objectThe wait duration statistics (avg
, min
, max
, total
) for Tasks accepted while in the TaskQueue. Calculation is based on the time when the Tasks were created. For transfers, the wait duration is counted from the moment the Task was created, and not from when the transfer was initiated.
wait_duration_until_canceled
type: objectThe wait duration statistics (avg
, min
, max
, total
) for Tasks canceled while in the TaskQueue.
wait_duration_in_queue_until_accepted
type: objectThe relative wait duration statistics (avg
, min
, max
, total
) for Tasks accepted while in the TaskQueue. Calculation is based on the time when the Tasks entered the TaskQueue.
workspace_sid
type: SID<WS>The SID of the Workspace that contains the TaskQueue.
^WS[0-9a-fA-F]{32}$
34
34
Note that for transfers, the splitByWaitTime does not include the wait time post transfer, and hence transfers should not impact SLA calculations based on the above endpoint.
_10GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/Statistics
WorkspaceSid
type: SID<WS>The SID of the Workspace with the TaskQueue to fetch.
^WS[0-9a-fA-F]{32}$
34
34
TaskQueueSid
type: SID<WQ>The SID of the TaskQueue for which to fetch statistics.
^WQ[0-9a-fA-F]{32}$
34
34
EndDate
type: string<date-time>Only calculate statistics from this date and time and earlier, specified in GMT as an ISO 8601 date-time.
Minutes
type: integerOnly calculate statistics since this many minutes in the past. The default is 15 minutes.
StartDate
type: string<date-time>Only calculate statistics from this date and time and later, specified in ISO 8601 format.
TaskChannel
type: stringOnly calculate real-time and cumulative statistics for the specified TaskChannel. Can be the TaskChannel's SID or its unique_name
, such as voice
, sms
, or default
.
SplitByWaitTime
type: stringA 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.
account_sid
type: SID<AC>The SID of the Account that created the TaskQueue resource.
^AC[0-9a-fA-F]{32}$
34
34
task_queue_sid
type: SID<WQ>The SID of the TaskQueue from which these statistics were calculated.
^WQ[0-9a-fA-F]{32}$
34
34
workspace_sid
type: SID<WS>The SID of the Workspace that contains the TaskQueue.
^WS[0-9a-fA-F]{32}$
34
34