Skip to content Skip to navigation Skip to topbar

On this page

Worker Statistics Resource

TaskRouter provides real-time, cumulative, and historical statistics for Workers. Historical statistics allow you to analyze data from the past 30 days. There are various APIs for retrieving the data that is meaningful to your business.

(warning)

Warning

These resources may not be accessible if your Workspace exceeds 100 workers. Please contact support for additional assistance.

WorkerStatistics Properties

Property nameTypeRequiredDescriptionChild properties

realtimeobject

Optional

Not PII

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

cumulativeobject

Optional

Not PII

An object that contains the cumulative statistics for the Worker.

account_sidSID<AC>

Optional

Not PII

The SID of the Account that created the Worker resource.

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

workspace_sidSID<WS>

Optional

Not PII

The SID of the Workspace that contains the Worker.

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

urlstring<uri>

Optional

Not PII

The absolute URL of the Worker statistics resource.

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

Fetch All Worker Statistics

GET /v1/Workspaces/{WorkspaceSid}/Workers/Statistics

Path parameters

Property nameTypeRequiredPIIDescription

WorkspaceSidSID<WS>required

Not PII

The SID of the Workspace with the Worker to fetch.

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

Query parameters

Property nameTypeRequiredPIIDescription

Minutesinteger

Optional

Not PII

Only calculate statistics since this many minutes in the past. The default 15 minutes. This is helpful for displaying statistics for the last 15 minutes, 240 minutes (4 hours), and 480 minutes (8 hours) to see trends.

StartDatestring<date-time>

Optional

Not PII

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

EndDatestring<date-time>

Optional

Not PII

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

TaskQueueSidSID<WQ>

Optional

Not PII

The SID of the TaskQueue for which to fetch Worker statistics.

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

TaskQueueNamestring

Optional

Not PII

The friendly_name of the TaskQueue for which to fetch Worker statistics.

FriendlyNamestring

Optional

Not PII

Only include Workers with friendly_name values that match this parameter.

TaskChannelstring

Optional

Not PII

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

Fetch a Worker Statistics Resource

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 fetchWorkerStatistics() {
11  const statistic = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers.statistics()
14    .fetch();
15
16  console.log(statistic.realtime);
17}
18
19fetchWorkerStatistics();

Output

1{
2  "cumulative": {
3    "reservations_created": 0,
4    "reservations_accepted": 0,
5    "reservations_rejected": 0,
6    "reservations_timed_out": 0,
7    "reservations_canceled": 0,
8    "reservations_rescinded": 0,
9    "activity_durations": [
10      {
11        "max": 0,
12        "min": 900,
13        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14        "friendly_name": "Offline",
15        "avg": 1080,
16        "total": 5400
17      },
18      {
19        "max": 0,
20        "min": 900,
21        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
22        "friendly_name": "Busy",
23        "avg": 1012,
24        "total": 8100
25      },
26      {
27        "max": 0,
28        "min": 0,
29        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
30        "friendly_name": "Idle",
31        "avg": 0,
32        "total": 0
33      },
34      {
35        "max": 0,
36        "min": 0,
37        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
38        "friendly_name": "Reserved",
39        "avg": 0,
40        "total": 0
41      }
42    ],
43    "start_time": "2008-01-02T00:00:00Z",
44    "end_time": "2008-01-02T00:00:00Z"
45  },
46  "realtime": {
47    "total_workers": 15,
48    "activity_statistics": [
49      {
50        "friendly_name": "Idle",
51        "workers": 0,
52        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
53      },
54      {
55        "friendly_name": "Busy",
56        "workers": 9,
57        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
58      },
59      {
60        "friendly_name": "Offline",
61        "workers": 6,
62        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
63      },
64      {
65        "friendly_name": "Reserved",
66        "workers": 0,
67        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
68      }
69    ]
70  },
71  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
72  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
73  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/Statistics"
74}

Fetch Real-Time Worker Statistics

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

GET /v1/Workspaces/{WorkspaceSid}/Workers/RealTimeStatistics

Path parameters

Property nameTypeRequiredPIIDescription

WorkspaceSidSID<WS>required

Not PII

The SID of the Workspace with the resource to fetch.

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

Query parameters

Property nameTypeRequiredPIIDescription

TaskChannelstring

Optional

Not PII

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

Retrieve Real-Time Worker 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 fetchWorkersRealTimeStatistics() {
11  const realTimeStatistic = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers.realTimeStatistics()
14    .fetch();
15
16  console.log(realTimeStatistic.accountSid);
17}
18
19fetchWorkersRealTimeStatistics();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/RealTimeStatistics",
5  "total_workers": 15,
6  "activity_statistics": [
7    {
8      "friendly_name": "Idle",
9      "workers": 0,
10      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
11    },
12    {
13      "friendly_name": "Busy",
14      "workers": 9,
15      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
16    },
17    {
18      "friendly_name": "Offline",
19      "workers": 6,
20      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
21    },
22    {
23      "friendly_name": "Reserved",
24      "workers": 0,
25      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
26    }
27  ]
28}

Real-time statistics relating to a list of Workers include the following:

Property	Description
TotalWorkers	The total number of Workers
ActivityStatistics	The current Worker status count breakdown by Activity

Fetch Cumulative Worker Statistics

Cumulative statistics allow you to analyze Worker data from the past 30 days.

1GET /v1/Workspaces/{WorkspaceSid}/Workers/CumulativeStatistics
2

Path parameters

Property nameTypeRequiredPIIDescription

WorkspaceSidSID<WS>required

Not PII

The SID of the Workspace with the resource to fetch.

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

Query parameters

Property nameTypeRequiredPIIDescription

EndDatestring<date-time>

Optional

Not PII

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

Minutesinteger

Optional

Not PII

StartDatestring<date-time>

Optional

Not PII

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

TaskChannelstring

Optional

Not PII

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

Retrieve Cumulative Worker 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 fetchWorkersCumulativeStatistics() {
11  const cumulativeStatistic = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers.cumulativeStatistics()
14    .fetch();
15
16  console.log(cumulativeStatistic.accountSid);
17}
18
19fetchWorkersCumulativeStatistics();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/CumulativeStatistics",
5  "reservations_created": 100,
6  "reservations_accepted": 100,
7  "reservations_rejected": 100,
8  "reservations_timed_out": 100,
9  "reservations_canceled": 100,
10  "reservations_rescinded": 100,
11  "activity_durations": [
12    {
13      "max": 0,
14      "min": 900,
15      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "friendly_name": "Offline",
17      "avg": 1080,
18      "total": 5400
19    },
20    {
21      "max": 0,
22      "min": 900,
23      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24      "friendly_name": "Busy",
25      "avg": 1012,
26      "total": 8100
27    },
28    {
29      "max": 0,
30      "min": 0,
31      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32      "friendly_name": "Idle",
33      "avg": 0,
34      "total": 0
35    },
36    {
37      "max": 0,
38      "min": 0,
39      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
40      "friendly_name": "Reserved",
41      "avg": 0,
42      "total": 0
43    }
44  ],
45  "start_time": "2015-07-30T20:00:00Z",
46  "end_time": "2015-07-30T20:00:00Z"
47}

Cumulative statistics relating to a list of Workers include the following over the interval:

Property	Description
ReservationsCreated	The total number of Reservations that were created
ReservationsAccepted	The total number of Reservations that were accepted
ReservationsRejected	The total number of Reservations that were rejected
ReservationsTimedOut	The total number of Reservations that were timed out
ReservationsCanceled	The total number of Reservations that were canceled
ReservationsRescinded	The total number of Reservations that were rescinded
ActivityDurations	The minimum, average, maximum and total time (in seconds) Workers spent in each Activity

Fetch A Specific Worker's Statistics

GET /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}/Statistics

Path parameters

Property nameTypeRequiredPIIDescription

WorkspaceSidSID<WS>required

Not PII

The SID of the Workspace with the WorkerChannel to fetch.

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

WorkerSidSID<WK>required

Not PII

The SID of the Worker with the WorkerChannel to fetch.

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

Query parameters

Property nameTypeRequiredPIIDescription

Minutesinteger

Optional

Not PII

StartDatestring<date-time>

Optional

Not PII

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

EndDatestring<date-time>

Optional

Not PII

Only include usage that occurred on or before this date, specified in GMT as an ISO 8601 date-time.

TaskChannelstring

Optional

Not PII

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

Retrieve a Specific Worker's 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 fetchWorkerInstanceStatistics() {
11  const statistic = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers("WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .statistics()
15    .fetch();
16
17  console.log(statistic.accountSid);
18}
19
20fetchWorkerInstanceStatistics();

Output

1{
2  "cumulative": {
3    "reservations_created": 100,
4    "reservations_accepted": 100,
5    "reservations_rejected": 100,
6    "reservations_timed_out": 100,
7    "reservations_canceled": 100,
8    "reservations_rescinded": 100,
9    "activity_durations": [
10      {
11        "max": 0,
12        "min": 900,
13        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14        "friendly_name": "Offline",
15        "avg": 1080,
16        "total": 5400
17      },
18      {
19        "max": 0,
20        "min": 900,
21        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
22        "friendly_name": "Busy",
23        "avg": 1012,
24        "total": 8100
25      },
26      {
27        "max": 0,
28        "min": 0,
29        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
30        "friendly_name": "Idle",
31        "avg": 0,
32        "total": 0
33      },
34      {
35        "max": 0,
36        "min": 0,
37        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
38        "friendly_name": "Reserved",
39        "avg": 0,
40        "total": 0
41      }
42    ],
43    "start_time": "2008-01-02T00:00:00Z",
44    "end_time": "2008-01-02T00:00:00Z"
45  },
46  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
47  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
48  "worker_sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
49  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics"
50}