VX Agents

API directory · Customer Support

Twilio TaskRouter Queues & Workers

v1.0.0 · 16 endpoints · 0 connections · shared by vx.ai

How long is the queue, and who is free to take it? For contact-center leads on Twilio TaskRouter: watch real-time and cumulative queue statistics, see which workers are Available or on break, flip a worker's activity, and create, reprioritise or cancel tasks and check their reservations.

Connect this API to an AI agent Browse all specs

What you can do with Twilio TaskRouter Queues & Workers via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /v1/Workspaces listWorkspaces List TaskRouter workspaces in the account
GET /v1/Workspaces/{WorkspaceSid}/RealTimeStatistics getWorkspaceRealTimeStatistics Right now: tasks waiting by status and workers by activity
GET /v1/Workspaces/{WorkspaceSid}/CumulativeStatistics getWorkspaceCumulativeStatistics Totals over a period: tasks created, accepted, canceled, wait times
GET /v1/Workspaces/{WorkspaceSid}/TaskQueues listTaskQueues List task queues
GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/RealTimeStatistics getTaskQueueRealTimeStatistics Live queue stats: tasks waiting, longest wait, available workers
GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}/CumulativeStatistics getTaskQueueCumulativeStatistics Queue totals over a period, including SLA and wait times
GET /v1/Workspaces/{WorkspaceSid}/Workers listWorkers List workers (agents), filtered by activity, availability or queue
GET /v1/Workspaces/{WorkspaceSid}/Workers/{Sid} getWorker Get one worker with activity and attributes
POST /v1/Workspaces/{WorkspaceSid}/Workers/{Sid} updateWorker Change a worker's activity (e.g. Available, Break) or attributes
GET /v1/Workspaces/{WorkspaceSid}/Workers/RealTimeStatistics getWorkersRealTimeStatistics Live count of workers in each activity
GET /v1/Workspaces/{WorkspaceSid}/Activities listActivities List activities (Available, Offline, Break...) and their SIDs
GET /v1/Workspaces/{WorkspaceSid}/Tasks listTasks List tasks by status, queue, workflow or attributes
POST /v1/Workspaces/{WorkspaceSid}/Tasks createTask Create a task to be routed by a workflow
GET /v1/Workspaces/{WorkspaceSid}/Tasks/{Sid} getTask Get one task with status, age, queue and attributes
POST /v1/Workspaces/{WorkspaceSid}/Tasks/{Sid} updateTask Change a task's priority or attributes, or cancel or complete it
GET /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations listTaskReservations List which workers a task was offered to and their responses

Authentication

accountSid_authToken

HTTP Basic

Twilio uses HTTP basic auth: username = Account SID (or API Key SID), password = Auth Token (or API Key Secret).

How to get a credential

  1. Sign in to the Twilio Console (https://console.twilio.com).
  2. Recommended: open Account > API keys & tokens > Create API key (Standard), and copy the key SID (SK...) and Secret (shown once).
  3. Or use the Account SID (AC...) and Auth Token from the Console dashboard.
  4. Find your TaskRouter Workspace SID (WS...) under TaskRouter > Workspaces (Flex accounts have one named Flex Task Assignment).

Permissions used

Twilio keys have no per-API scopes; a Standard key can call every TaskRouter operation in the account.

Access Operations
Read listWorkspaces, getWorkspaceRealTimeStatistics, getWorkspaceCumulativeStatistics, listTaskQueues, getTaskQueueRealTimeStatistics, getTaskQueueCumulativeStatistics, listWorkers, getWorker, getWorkersRealTimeStatistics, listActivities, listTasks, getTask, listTaskReservations
Write updateWorker, createTask, updateTask

Common errors

Status Meaning Fix
401 (20003) Wrong SID/secret pair Use the API key SID with its own secret, or the Account SID with the Auth Token.
403 Key restricted or account suspended Use a Standard API key on an active account.
404 (20404) Wrong Workspace, queue, worker or task SID List workspaces and queues first; SIDs belong to one workspace.
400 Bad parameter, e.g. Attributes not valid JSON Send Attributes as a JSON string.
429 (20429) Too many requests Back off and retry.

Store the SID and secret as a VX Agents basic-auth credential.

Usage guide

Setup

  1. Add a Twilio API key SID + secret (or Account SID + Auth Token) as a VX Agents basic-auth credential.
  2. Pin WorkspaceSid (WS...) on every operation; listWorkspaces shows it (Flex accounts use "Flex Task Assignment").

Check the floor and react

  1. getWorkspaceRealTimeStatistics for the big picture: tasks by assignment status, longest wait and workers per activity.
  2. listTaskQueues, then getTaskQueueRealTimeStatistics per queue: tasks_by_status, longest_task_waiting_age (seconds) and total_available_workers.
  3. Who can help? listWorkers with Available=true, or with ActivityName (e.g. Break) or TaskQueueName; getWorkersRealTimeStatistics counts workers per activity.
  4. To move an agent, listActivities for the activity SIDs (WA...), confirm with the user, then updateWorker with ActivitySid.
  5. Stuck tasks: listTasks with AssignmentStatus (pending, reserved, assigned, wrapping) and TaskQueueSid, Ordering=DateCreated:asc for the oldest; getTask for details and listTaskReservations for who was offered it and what they answered.
  6. After confirming with the user, updateTask to raise Priority, change Attributes, or set AssignmentStatus=canceled with a Reason (or completed for an assigned task).

Reports

getWorkspaceCumulativeStatistics and getTaskQueueCumulativeStatistics take Minutes (look-back window) or StartDate/EndDate (ISO 8601), and SplitByWaitTime (e.g. 20,60) to count tasks answered within each threshold, a quick service-level view.

Creating tasks

createTask with WorkflowSid and Attributes as a JSON string (e.g. {"type":"support","customer":"+15551234567"}), optional Priority, Timeout (seconds) and TaskChannel (default, voice, chat, sms). The workflow routes it to a queue and reserves a worker: confirm first.

Good to know

  • Write bodies are form-encoded; Attributes must be valid JSON in a string.
  • Lists page with PageSize (max 1000) and the next_page_url/PageToken in meta.
  • Changing a worker's activity or canceling a task affects live routing immediately.
  • Deleting workers, queues or workspaces is not part of this spec.

Source: Twilio TaskRouter REST API reference (https://www.twilio.com/docs/taskrouter/api), checked 2026-10-23.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Twilio TaskRouter Queues & Workers” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs