Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

TaskRouter Resource Limits

Twilio TaskRouter has default limits on resources and endpoints. If you are running into these limits, please reach out to our support team(link takes you to an external page). We're happy to help and evaluate whether we can increase some of those limits for you.

To view the default limits as well as your account specific limits, please log into the Twilio Console and navigate to your TaskRouter Workspace's Limits page.

Why Limits Are Being Used

why-limits-are-being-used page anchor

Limits are generally put in place as a defensive measure for services. Even highly scalable systems and shared services need to be protected from excessive use, intended and unintended, to maintain stability and availability of the service. For the system to perform well, clients must also be designed with rate limiting in mind to reduce the chances of cascading failure. Rate limiting on both the client side and the server side is crucial for maximizing throughput and minimizing end-to-end latency across distributed systems.

We can't wait to see what you build with TaskRouter and Flex! For the system and your solution to perform well it is imperative to build it using REST API: Best Practices, such as retries with exponential backoff to properly handle the API response Error 429 "Too Many Requests"(link takes you to an external page).

When utilizing TaskRouter Statistics endpoints, we recommended leveraging caching from your backend application to ensure each endpoint can support your scaling needs. In scenarios where these endpoints are used from a client application, we recommend implementing a sync layer, e.g., via Twilio Sync, to help synchronize each endpoint's state across all clients, in order to ensure each endpoint can scale with your user growth.

You can also engage our Twilio Professional Services team to help you build on the TaskRouter platform and design the best solution for your organization.

Resource Configuration Limits

resource-configuration-limits page anchor

Unlike rate and resource limits, the resource configuration limits are non-changeable limits.



The limits on JSON attributes include whitespace. You save a few bytes by using a JSON minifier and creating/updating the Resource through the REST API.

Worker AttributesThe maximum size of the JSON string used for defining Worker attributes.4096 characters
Task AttributesThe maximum size of the JSON string used for defining Task attributes.4096 characters
Workflow ConfigurationThe maximum size of the JSON string used to define a Workflow.1038576 bytes (1MB)
Task Timeout (Pending and Reserved Tasks)The maximum amount of time a Task can exist in a pending or reserved state before timing out (task.timeout) and being cancelled.1209600 seconds (2 weeks)
Task Timeout (Assigned Tasks)The maximum amount of time a Task can stay assigned to a Worker before being deleted by the system (task.system-deleted).86400 seconds (24 hours)
Max Reservation Timeout86400 seconds (24 hours)
Max Reserved WorkersThe maximum number of Workers that can simultaneously be offered a reservation for a Task in a TaskQueue with Multi-Reservation enabled.50

Reservations per TaskNumber of times a Task can move from status pending to reserved before being cancelled. In a multi-reservation setup, the simultaneous reservation of multiple workers equates to only a single Task state change from status pending to reserved.1,000
Worker Statistics Endpoint CapWorker Statistics REST API endpoints are not accessible by default if you have over these many Workers in your Workspace.100
Waiting Voice Calls per TaskRouter WorkflowEvery TaskRouter workflow that handles voice calls has a Programmable Voice queue under the hood. This refers to the default size of that queue.100 (max 5000)

Updating the Waiting Voice Calls per TaskRouter Workflow Limit with Twilio CLI

updating-the-waiting-voice-calls-per-taskrouter-workflow-limit-with-twilio-cli page anchor

The limit for the number of waiting voice calls is set on a per-workflow basis and can be updated through our REST API or by using Twilio CLI and the steps below.

Step 1: Find your TaskRouter Workflow SID

step-1-find-your-taskrouter-workflow-sid page anchor

Find the workflow sid for the TaskRouter workflow that you are running into queue limit issues with, either through console or by running the following cli command.

List all TaskRouter Workflows.

list-all-taskrouter-workflows page anchor

twilio api:taskrouter:v1:workspaces:workflows:list --workspace-sid WSxxx

Step 2: Find the Queue that matches your TaskRouter Workflow

step-2-find-the-queue-that-matches-your-taskrouter-workflow page anchor

Find the queue sid that matches your queue by running the following cli command. The friendlyName for the queue you are looking for will be the workflow sid you grabbed in step 1.

List all Programmable Voice Queues.

list-all-programmable-voice-queues page anchor

twilio api:core:queues:list --properties "sid,friendlyName,maxSize"

Step 3: Update the maxSize of your Queue

step-3-update-the-maxsize-of-your-queue page anchor

Update the max size of the queue using the following cli command. The max-size property can be an integer between 0 and 5000.

Update the Max Size of a Programmable Voice Queue.

update-the-max-size-of-a-programmable-voice-queue page anchor

twilio api:core:queues:update --sid QUxxx --max-size 500 --properties "sid,friendlyName,maxSize"

Rate this page: