REST API: Workspace Statistics

TaskRouter provides real time and historical statistics for Workspaces. Historical statistics allow you to analyze data from the past 30 days.

Workspace Statistics

Resource URI

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

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

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
4  "cumulative": {
5    "avg_task_acceptance_time": 0,
6    "start_time": "2008-01-02T00:00:00Z",
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    "end_time": "2008-01-02T00:00:00Z",
14    "tasks_canceled": 0,
15    "tasks_created": 0,
16    "tasks_deleted": 0,
17    "tasks_moved": 0,
18    "tasks_timed_out_in_workflow": 0
19  },
20  "realtime": {
21    "activity_statistics": [
22      {
23        "friendly_name": "Offline",
24        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25        "workers": 1
26      },
27      {
28        "friendly_name": "Idle",
29        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
30        "workers": 0
31      },
32      {
33        "friendly_name": "80fa2beb-3a05-11e5-8fc8-98e0d9a1eb73",
34        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
35        "workers": 0
36      },
37      {
38        "friendly_name": "Reserved",
39        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
40        "workers": 0
41      },
42      {
43        "friendly_name": "Busy",
44        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
45        "workers": 0
46      },
47      {
48        "friendly_name": "817ca1c5-3a05-11e5-9292-98e0d9a1eb73",
49        "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
50        "workers": 0
51      }
52    ],
53    "longest_task_waiting_age": 0,
54    "longest_task_waiting_sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
55    "tasks_by_status": {
56      "assigned": 0,
57      "pending": 0,
58      "reserved": 0,
59      "wrapping": 0
60    },
61    "total_tasks": 0,
62    "total_workers": 1
63  },
64  "workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
65}

Parameter	Description
Minutes	Filter cumulative statistics by up to 'x' minutes in the past. This is helpful for statistics for the last 15 minutes, 240 minutes (4 hours), and 480 minutes (8 hours) to see trends. Defaults to 15 minutes.
StartDate	Filter cumulative statistics by a start date. This is helpful for defining a range of statistics to capture. Input is a GMT ISO 8601 Timestamp
EndDate	Filter cumulative statistics by an end date. This is helpful for defining a range of statistics to capture. Input is a GMT ISO 8601 Timestamp
TaskChannel	Filter real-time and cumulative statistics by TaskChannel. Takes in a Unique Name ("voice", "sms", "default", etc.) or a TaskChannelSid.
SplitByWaitTime	A comma separated values for viewing splits of tasks canceled and accepted above the given threshold in seconds. Ex: "5,30" would show splits of tasks that were canceled or accepted before or after 5 seconds and respectively, 30 seconds. This is great for showing short abandoned tasks or tasks that failed to meet your SLA.

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

Real Time

Real time statistics relating to a Workspace include the following:

Property	Description
LongestTaskWaitingSid	The ID of the longest waiting Task
LongestTaskWaitingAge	The age of the longest waiting Task
TotalTasks	The total number of Tasks
TotalWorkers	The total number of Workers in the workspace
TasksByStatus	The Tasks broken down by status (for example: pending: 1, reserved = 3, assigned = 2, completed = 5)
ActivityStatistics	A breakdown of Workers by Activity (for example: Idle : 0, Busy: 5, Reserved = 0, Offline = 2)

Cumulative

Cumulative statistics relating to a Workspace include the following over the interval:

Property	Description
TasksCreated	The total number of Tasks created
TasksCanceled	The total number of Tasks that were canceled
TasksCompleted	The total number of Tasks that were completed
TasksDeleted	The total number of Tasks that were deleted
TasksMoved	The total number of Tasks that were moved from one queue to another
TasksTimedOutInWorkflow	The total number of Tasks that were timed out of their Workflows (and deleted)
AvgTaskAcceptanceTime	The average time (in seconds) from Task creation to acceptance
ReservationsCreated	The total number of Reservations that were created for Workers
ReservationsAccepted	The total number of Reservations accepted by Workers
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
WaitDurationUntilCanceled	The wait duration stats (avg, min, max, total) for tasks that were canceled.
WaitDurationUntilAccepted	The wait duration stats (avg, min, max, total) for tasks that were accepted.
SplitByWaitTime	The splits of the tasks canceled and accepted based on the provided SplitByWaitTime parameter.

Workspace RealTime Statistics

If you are only concerned with the real time statistics of your workspace, 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}/RealTimeStatistics
2

Retrieve workspace real time 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 fetchWorkspaceRealTimeStatistics() {
11  const realTimeStatistic = await client.taskrouter.v1
12    .workspaces("WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .realTimeStatistics()
14    .fetch();
15
16  console.log(realTimeStatistic.accountSid);
17}
18
19fetchWorkspaceRealTimeStatistics();

Output

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

Parameter	Description
TaskChannel	Filter real-time statistics by TaskChannel. Takes in a Unique Name ("voice", "sms", "default", etc.) or a TaskChannelSid.

Real Time

Real time statistics relating to a Workspace include the following:

Property	Description
LongestTaskWaitingSid	The ID of the longest waiting Task
LongestTaskWaitingAge	The age of the longest waiting Task
TotalTasks	The total number of Tasks
TotalWorkers	The total number of Workers in the workspace
TasksByStatus	The Tasks broken down by status (for example: pending: 1, reserved = 3, assigned = 2, completed = 5)
ActivityStatistics	A breakdown of Workers by Activity (for example: Idle : 0, Busy: 5, Reserved = 0, Offline = 2)

Workspace 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}/CumulativeStatistics
2

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

Output

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

Parameter	Description
Minutes	Filter cumulative statistics by up to 'x' minutes in the past. This is helpful for statistics for the last 15 minutes, 240 minutes (4 hours), and 480 minutes (8 hours) to see trends. Defaults to 15 minutes.
StartDate	Filter cumulative statistics by a start date. This is helpful for defining a range of statistics to capture. Input is a GMT ISO 8601 Timestamp
EndDate	Filter cumulative statistics by an end date. This is helpful for defining a range of statistics to capture. Input is a GMT ISO 8601 Timestamp
TaskChannel	Filter cumulative statistics by TaskChannel. Takes in a Unique Name ("voice", "sms", "default", etc.) or a TaskChannelSid.
SplitByWaitTime	A comma separated values for viewing splits of tasks canceled and accepted above the given threshold in seconds. Ex: "5,30" would show splits of tasks that were canceled or accepted before or after 5 seconds and respectively, 30 seconds. This is great for showing short abandoned tasks or tasks that failed to meet your SLA.

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

Cumulative statistics relating to a Workspace include the following over the interval:

Property	Description
TasksCreated	The total number of Tasks created
TasksCanceled	The total number of Tasks that were canceled
TasksCompleted	The total number of Tasks that were completed
TasksDeleted	The total number of Tasks that were deleted
TasksMoved	The total number of Tasks that were moved from one queue to another
TasksTimedOutInWorkflow	The total number of Tasks that were timed out of their Workflows (and deleted)
AvgTaskAcceptanceTime	The average time (in seconds) from Task creation to acceptance
ReservationsCreated	The total number of Reservations that were created for Workers
ReservationsAccepted	The total number of Reservations accepted by Workers
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
WaitDurationUntilCanceled	The wait duration stats (avg, min, max, total) for tasks that were canceled.
WaitDurationUntilAccepted	The wait duration stats (avg, min, max, total) for tasks that were accepted.
SplitByWaitTime	The splits of the tasks canceled and accepted based on the provided SplitByWaitTime parameter.