Rate this page:

Lifecycle of a Task: Task State

A Task is the core of TaskRouter — It represents a single item of work waiting to be processed. TaskRouter's primary role is to match a Task with a Worker, someone who can take action on the pending Task.

All of the other TaskRouter entities (TaskQueues, Activities, Channels, and especially Workflows) are used to support this assignment.

Task State

A Task progresses through a series of states, starting with pending, until successfully ending with completed. These Task states are closely associated with the Reservations that attempt to assign a Task to a Worker.

Task States


When a Task is created, it starts as pending. A Task will stay in pending until a matching Worker is found via a Workflow. Workflows and Assignment provides detail on how a Task is evaluated by a Workflow to be assigned.


A Task moves to reserved when a Reservation is created with a matching Worker.

Once reserved, a Task will move back to pending if the Reservation is rejected or the Reservation Timeout is reached. Otherwise, if the Reservation is accepted, the Task will move to assigned.

For multi-reservations, where multiple reservations are created simultaneously for a Task, the Task will only move back to pending if all of the created reservations end without acceptance.


At any point until the Task has been assigned, the Task can be canceled. This will primarily occur for one of three reasons:

  • The Task is canceled by an API request
  • The Task times-out according to the TTL set on the Task
  • The Task passes the final step in a Workflow without an accepted Reservation

canceled is one of two terminal states for a Task (the other is completed), and the Task will be deleted five minutes after moving into this state. Once a Task is canceled, it cannot be queued for assignment anymore.


Once a Reservation has been accepted, the Task is assigned. This is the period where the work represented by the Task actually gets done. For example, if the Task represents a voice call, the Worker would be connected to the other call participant.

After a Task has been assigned, it will only terminate at completed. An assigned Task won't move to canceled.

If the Task is not transitioned to completed within 24 hours, it is being deleted from the system after being in the assigned state for 24 hours.

Wrapping and Completed

Once the work associated with a Task is finished, the Task can be completed. For some Tasks, this will happen automatically by TaskRouter — for example, voice calls accepted via reservation.conference. Otherwise, a Task must be completed via the API.

In a multitasking Workspace, Tasks will move to wrapping first when the state is automatically transitioned by TaskRouter. Tasks can also be manually moved into wrapping by the API. wrapping Tasks must be moved to completed via the API.

The Task will be deleted five minutes after moving into completed.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more