Skip to content Skip to navigation Skip to topbar

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.

(warning)

Warning

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

1GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/RealTimeStatistics
2

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace with the TaskQueue to fetch.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

taskQueueSidSID<WQ>

required

The SID of the TaskQueue for which to fetch statistics.

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

Property nameTypeRequiredPIIDescription

taskChannelstring

Optional

The 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:

Property nameTypeRequiredDescriptionChild properties

accountSidSID<AC>

Optional

The SID of the Account that created the TaskQueue resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

activityStatisticsarray

Optional

The number of current Workers by Activity.

longestTaskWaitingAgeinteger

Optional

The age of the longest waiting Task.

Default: 0

longestTaskWaitingSidSID<WT>

Optional

The SID of the longest waiting Task.

Pattern: ^WT[0-9a-fA-F]{32}$Min length: 34Max length: 34

longestRelativeTaskAgeInQueueinteger

Optional

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

Default: 0

longestRelativeTaskSidInQueueSID<WT>

Optional

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

Pattern: ^WT[0-9a-fA-F]{32}$Min length: 34Max length: 34

taskQueueSidSID<WQ>

Optional

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

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

tasksByPriority

Optional

The number of Tasks by priority. For example: {"0": "10", "99": "5"} shows 10 Tasks at priority 0 and 5 at priority 99.

tasksByStatus

Optional

The number of Tasks by their current status. For example: {"pending": "1", "reserved": "3", "assigned": "2", "completed": "5"}.

totalAvailableWorkersinteger

Optional

The total number of Workers in the TaskQueue with an available status. Workers with an available status may already have active interactions or may have none.

Default: 0

totalEligibleWorkersinteger

Optional

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

Default: 0

totalTasksinteger

Optional

The total number of Tasks.

Default: 0

workspaceSidSID<WS>

Optional

The SID of the Workspace that contains the TaskQueue.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

urlstring<uri>

Optional

The absolute URL of the TaskQueue statistics resource.

Examples

Retrieving TaskQueue RealTime Statistics

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchTaskQueueRealTimeStatistics() {
11  const realTimeStatistic = await client.taskrouter.v1
12    .workspaces("WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .taskQueues("WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .realTimeStatistics()
15    .fetch();
16
17  console.log(realTimeStatistic.accountSid);
18}
19
20fetchTaskQueueRealTimeStatistics();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "longest_task_waiting_age": 100,
3  "longest_task_waiting_sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "longest_relative_task_age_in_queue": 100,
5  "longest_relative_task_sid_in_queue": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7  "tasks_by_status": {
8    "reserved": 0,
9    "pending": 0,
10    "assigned": 0,
11    "wrapping": 0
12  },
13  "total_eligible_workers": 100,
14  "activity_statistics": [
15    {
16      "friendly_name": "Idle",
17      "workers": 0,
18      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
19    },
20    {
21      "friendly_name": "Busy",
22      "workers": 9,
23      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
24    },
25    {
26      "friendly_name": "Offline",
27      "workers": 6,
28      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
29    },
30    {
31      "friendly_name": "Reserved",
32      "workers": 0,
33      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
34    }
35  ],
36  "tasks_by_priority": {},
37  "total_tasks": 100,
38  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
39  "workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
40  "total_available_workers": 100,
41  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TaskQueues/WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics"
42}

Bulk retrieval of TaskQueue RealTime Statistics

To retrieve real-time statistics for multiple queues, you can utilize the below endpoint.

Resource URI

1POST /v1/Workspaces/{WorkspaceSid}/TaskQueues/RealTimeStatistics
2

Uri Parameters
WorkspaceSid `POST` `SID<WS>` `NOT PII` 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:

Property nameTypeRequiredDescriptionChild properties

accountSidSID<AC>

Optional

The SID of the Account that created the TaskQueue resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

workspaceSidSID<WS>

Optional

The SID of the Workspace that contains the TaskQueue.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

taskQueueDataarray

Optional

The 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.

taskQueueResponseCountinteger

Optional

The number of TaskQueue statistics received in task_queue_data.

Default: 0

urlstring<uri>

Optional

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 requests per second. If this rate limit is exceeded, an HTTP 429 error is returned.

Examples

Bulk retrieval of TaskQueue RealTime Statistics

1curl --location --request POST 'https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/TaskQueues/RealTimeStatistics' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4   "queueSids": [
5        "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6        "WQYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
7        "WQZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ"
8   ]
9}'

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

1GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/CumulativeStatistics
2

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace with the TaskQueue to fetch.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

taskQueueSidSID<WQ>

required

The SID of the TaskQueue for which to fetch statistics.

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

Property nameTypeRequiredPIIDescription

endDatestring<date-time>

Optional

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

minutesinteger

Optional

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

startDatestring<date-time>

Optional

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

taskChannelstring

Optional

Only calculate cumulative statistics on this TaskChannel. Can be the TaskChannel's SID or its unique_name, such as voice, sms, or default.

splitByWaitTimestring

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:

Property nameTypeRequiredDescriptionChild properties

accountSidSID<AC>

Optional

The SID of the Account that created the TaskQueue resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

avgTaskAcceptanceTimeinteger

Optional

The average time in seconds between Task creation and acceptance.

Default: 0

startTimestring<date-time>

Optional

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

endTimestring<date-time>

Optional

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

reservationsCreatedinteger

Optional

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

Default: 0

reservationsAcceptedinteger

Optional

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

Default: 0

reservationsRejectedinteger

Optional

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

Default: 0

reservationsTimedOutinteger

Optional

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

Default: 0

reservationsCanceledinteger

Optional

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

Default: 0

reservationsRescindedinteger

Optional

The total number of Reservations rescinded.

Default: 0

splitByWaitTime

Optional

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

taskQueueSidSID<WQ>

Optional

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

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

waitDurationUntilAccepted

Optional

The 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.

waitDurationUntilCanceled

Optional

The wait duration statistics (avg, min, max, total) for Tasks canceled while in the TaskQueue.

waitDurationInQueueUntilAccepted

Optional

The 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.

tasksCanceledinteger

Optional

The total number of Tasks canceled in the TaskQueue.

Default: 0

tasksCompletedinteger

Optional

The total number of Tasks completed in the TaskQueue.

Default: 0

tasksDeletedinteger

Optional

The total number of Tasks deleted in the TaskQueue.

Default: 0

tasksEnteredinteger

Optional

The total number of Tasks entered into the TaskQueue.

Default: 0

tasksMovedinteger

Optional

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

Default: 0

workspaceSidSID<WS>

Optional

The SID of the Workspace that contains the TaskQueue.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

urlstring<uri>

Optional

The absolute URL of the TaskQueue statistics resource.

(information)

Info

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.

Examples

Retrieving TaskQueue Cumulative Statistics

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchTaskQueueCumulativeStatistics() {
11  const cumulativeStatistic = await client.taskrouter.v1
12    .workspaces("WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .taskQueues("WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .cumulativeStatistics()
15    .fetch();
16
17  console.log(cumulativeStatistic.accountSid);
18}
19
20fetchTaskQueueCumulativeStatistics();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "reservations_created": 100,
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "reservations_rejected": 100,
5  "tasks_completed": 100,
6  "end_time": "2015-07-30T20:00:00Z",
7  "tasks_entered": 100,
8  "tasks_canceled": 100,
9  "reservations_accepted": 100,
10  "task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
11  "reservations_timed_out": 100,
12  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TaskQueues/WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics",
13  "wait_duration_until_canceled": {
14    "avg": 0,
15    "min": 0,
16    "max": 0,
17    "total": 0
18  },
19  "wait_duration_until_accepted": {
20    "avg": 0,
21    "min": 0,
22    "max": 0,
23    "total": 0
24  },
25  "wait_duration_in_queue_until_accepted": {
26    "avg": 0,
27    "min": 0,
28    "max": 0,
29    "total": 0
30  },
31  "split_by_wait_time": {
32    "5": {
33      "above": {
34        "tasks_canceled": 0,
35        "reservations_accepted": 0
36      },
37      "below": {
38        "tasks_canceled": 0,
39        "reservations_accepted": 0
40      }
41    },
42    "10": {
43      "above": {
44        "tasks_canceled": 0,
45        "reservations_accepted": 0
46      },
47      "below": {
48        "tasks_canceled": 0,
49        "reservations_accepted": 0
50      }
51    }
52  },
53  "start_time": "2015-07-30T20:00:00Z",
54  "tasks_moved": 100,
55  "reservations_canceled": 100,
56  "workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
57  "tasks_deleted": 100,
58  "reservations_rescinded": 100,
59  "avg_task_acceptance_time": 100
60}

TaskQueue Instance Statistics

Resource URI

1GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/Statistics
2

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace with the TaskQueue to fetch.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

taskQueueSidSID<WQ>

required

The SID of the TaskQueue for which to fetch statistics.

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

Property nameTypeRequiredPIIDescription

endDatestring<date-time>

Optional

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

minutesinteger

Optional

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

startDatestring<date-time>

Optional

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

taskChannelstring

Optional

Only 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.

splitByWaitTimestring

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.

(warning)

Warning

Minutes cannot be used in combination with StartDate and EndDate parameters. If no parameters are passed, 15 minutes will be the default.

Property nameTypeRequiredDescriptionChild properties

accountSidSID<AC>

Optional

The SID of the Account that created the TaskQueue resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

cumulative

Optional

An object that contains the cumulative statistics for the TaskQueue.

realtime

Optional

An object that contains the real-time statistics for the TaskQueue.

taskQueueSidSID<WQ>

Optional

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

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

workspaceSidSID<WS>

Optional

The SID of the Workspace that contains the TaskQueue.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

urlstring<uri>

Optional

The absolute URL of the TaskQueue statistics resource.

Examples

Retrieving TaskQueue Instance Statistics

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchTaskQueueStatistics() {
11  const statistic = await client.taskrouter.v1
12    .workspaces("WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .taskQueues("WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .statistics()
15    .fetch();
16
17  console.log(statistic.accountSid);
18}
19
20fetchTaskQueueStatistics();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TaskQueues/WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
4  "cumulative": {
5    "avg_task_acceptance_time": 0,
6    "end_time": "2015-08-18T08:42:34Z",
7    "reservations_accepted": 0,
8    "reservations_canceled": 0,
9    "reservations_created": 0,
10    "reservations_rejected": 0,
11    "reservations_rescinded": 0,
12    "reservations_timed_out": 0,
13    "start_time": "2015-08-18T08:27:34Z",
14    "tasks_canceled": 0,
15    "tasks_deleted": 0,
16    "tasks_entered": 0,
17    "tasks_moved": 0
18  },
19  "realtime": {
20    "activity_statistics": [
21      {
22        "friendly_name": "Offline",
23        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24        "workers": 0
25      },
26      {
27        "friendly_name": "Idle",
28        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29        "workers": 0
30      },
31      {
32        "friendly_name": "80fa2beb-3a05-11e5-8fc8-98e0d9a1eb73",
33        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
34        "workers": 0
35      },
36      {
37        "friendly_name": "Reserved",
38        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
39        "workers": 0
40      },
41      {
42        "friendly_name": "Busy",
43        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
44        "workers": 0
45      },
46      {
47        "friendly_name": "817ca1c5-3a05-11e5-9292-98e0d9a1eb73",
48        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
49        "workers": 0
50      }
51    ],
52    "longest_task_waiting_age": 0,
53    "longest_task_waiting_sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
54    "tasks_by_status": {
55      "assigned": 0,
56      "pending": 0,
57      "reserved": 0,
58      "wrapping": 0
59    },
60    "total_available_workers": 0,
61    "total_eligible_workers": 0,
62    "total_tasks": 0
63  },
64  "task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
65  "workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
66}