Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Execution

An Execution represents a specific person's run through a Flow. An Execution is active while the user is in the Flow, and it is considered ended when they stop responding to messages or hang up their call.

The Execution resource can be used to retrieve information about existing Executions or to create new Executions for outbound use cases (e.g. surveys, appointment reminders).

Subscribe to Real-time Studio Events

You can now subscribe to Studio Events for Executions and Steps instead of polling via the REST API. Simplify your data ingestion with Event Streams for Studio.

Try Studio Events(link takes you to an external page)

Create an Execution to Trigger a Flow

create-an-execution-to-trigger-a-flow page anchor

To trigger a new Execution of your Flow via the REST API, make an HTTP POST request to:

https://studio.twilio.com/v2/Flows/{FlowSid}/Executions

(warning)

Warning

Studio Rate Limits
Be sure to review Studio's rate limits when building your application.

Required Parameters

ParameterDescription
ToThe Contact phone number (or other identifier) to start a Studio Flow Execution, available as variable {{contact.channel.address}}
FromThe Twilio phone number (or other identifier such as a SID of a Messaging Service) to send messages or initiate calls from during the Flow Execution, available as variable {{flow.channel.address}}

Important: If you are using a phone number as an identifier, make sure to format the To / From phone numbers as E.164 (e.g. +1xxxxxxxxxx) to ensure a Contact's session is tracked correctly. Only one Execution can be active at a time for the same To/From combination.

Optional Parameters

ParameterDescription
ParametersJSON data that will be added to your flow's context and can be accessed as variables inside your flow. For example, if you pass in Parameters={"name":"Zeke"}, then inside a widget you can reference the variable {{flow.data.name}}, which will return the string "Zeke". Note: At the HTTP layer, the JSON parameter must be explicitly passed as a URL encoded string. However, the Twilio Helper Libraries accept a native object and automatically serialize and encode the JSON string for you.

Quick Example

quick-example page anchor

Here is a quick example of creating an Execution via the REST API using the Twilio Node.js Helper Library(link takes you to an external page):

1
const client = require('twilio')(accountSid, authToken);

2


3
client.studio.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')

4
             .executions

5
             .create({

6
                 to: '+15558675310',

7
                 from: '+15017122661',

8
                 parameters: {

9
                   name: 'Zeke'

10
                 }})

11
             .then(execution => console.log(execution.sid));
(warning)

Warning

Important: When triggering flows with the API, don't forget to also configure your phone number (or other identifier) with your Studio Flow! If you don't configure the phone number, users won't be able to reply to your messages or interact with your IVR.

See the following for examples:

Additionally, if a number is configured with a Messaging Service, be sure to use the Messaging Service identifier as the From identifier so that users can reply to your messages, and ensure that your Messaging Service inbound settings are configured to point to the webhook URLfrom your Twilio Studio Flow.

Execution Properties

execution-properties page anchor
Property nameTypeRequiredDescriptionChild properties
sidSID<FN>Optional
Not PII

The unique string that we created to identify the Execution resource.

Pattern: ^FN[0-9a-fA-F]{32}$Min length: 34Max length: 34
account_sidSID<AC>Optional
Not PII

The SID of the Account that created the Execution resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
flow_sidSID<FW>Optional
Not PII

The SID of the Flow.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
contact_channel_addressstringOptional
PII MTL: 30 days

The phone number, SIP address or Client identifier that triggered the Execution. Phone numbers are in E.164 format (e.g. +16175551212). SIP addresses are formatted as name@company.com. Client identifiers are formatted client:name.

contextobjectOptional
PII MTL: 30 days

The current state of the Flow's Execution. As a flow executes, we save its state in this context. We save data that your widgets can access as variables in configuration fields or in text areas as variable substitution.

statusenum<string>Optional
Not PII

The status of the Execution. Can be: active or ended.

Possible values:
activeended
date_createdstring<date-time>Optional
Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.

date_updatedstring<date-time>Optional
Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.

urlstring<uri>Optional
Not PII

The absolute URL of the resource.

linksobject<uri-map>Optional
Not PII

The URLs of nested resources.

Create a new execution

create-a-new-execution page anchor
POST https://studio.twilio.com/v2/Flows/{FlowSid}/Executions

Creating a new Execution will attempt to trigger a new Studio flow between two contacts.

(warning)

Handling Conflicting Executions: New Behavior in v2

If you attempt to create an Execution using v2 of this API and we find there is an active Execution for the same To/From combination, the API will return an error with the 409 Conflict HTTP status. This error response will provide a reference to the existing Execution SID so you can end it, if appropriate, and try your Create request again.

Example error response:

1
{

2
    "code": 20409,

3
    "details": {

4
        "conflicting_execution_sid": "FNf11d38169ef8920ae5e2b10acbb0374d"

5
    },

6
    "message": "Execution FNf11d38169ef8920ae5e2b10acbb0374d is already active for this contact. End the active Execution before creating a new one",

7
    "more_info": "https://www.twilio.com/docs/errors/20409",

8
    "status": 409

9
}

If we are able to create a new Execution with your To/From information, the API will return the 201 Created HTTP status.

If you're still using v1 of this API, creating an Execution where one is already active will not create a new Execution or return an error, and will instead always return a 200 OK code with the existing active Execution.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
FlowSidSID<FW>required
Not PII

The SID of the Excecution's Flow.

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

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Tostring<phone-number>required
Not PII

The Contact phone number to start a Studio Flow Execution, available as variable {{contact.channel.address}}.

Fromstring<phone-number>required
Not PII

The Twilio phone number to send messages or initiate calls from during the Flow's Execution. Available as variable {{flow.channel.address}}. For SMS, this can also be a Messaging Service SID.

ParametersobjectOptional
Not PII

JSON data that will be added to the Flow's context and that can be accessed as variables inside your Flow. For example, if you pass in Parameters={"name":"Zeke"}, a widget in your Flow can reference the variable {{flow.data.name}}, which returns "Zeke". Note: the JSON value must explicitly be passed as a string, not as a hash object. Depending on your particular HTTP library, you may need to add quotes or URL encode the JSON string.

Create ExecutionLink to code sample: Create Execution
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createExecution() {

11
  const execution = await client.studio.v2

12
    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .executions.create({

14
      from: "+15017122661",

15
      to: "+15558675310",

16
    });

17


18
  console.log(execution.sid);

19
}

20


21
createExecution();

Output

1
{

2
  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "sid": "FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

6
  "context": {},

7
  "contact_channel_address": "+18001234567",

8
  "status": "active",

9
  "date_created": "2015-07-30T20:00:00Z",

10
  "date_updated": "2015-07-30T20:00:00Z",

11
  "links": {

12
    "steps": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",

13
    "execution_context": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"

14
  }

15
}
Create an Execution with custom parametersLink to code sample: Create an Execution with custom parameters
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createExecution() {

11
  const execution = await client.studio.v2

12
    .flows("FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .executions.create({

14
      from: "+14155552344",

15
      parameters: {

16
        foo: "bar",

17
      },

18
      to: "+14155552345",

19
    });

20


21
  console.log(execution.sid);

22
}

23


24
createExecution();

Output

1
{

2
  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "sid": "FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

6
  "context": {},

7
  "contact_channel_address": "+18001234567",

8
  "status": "active",

9
  "date_created": "2015-07-30T20:00:00Z",

10
  "date_updated": "2015-07-30T20:00:00Z",

11
  "links": {

12
    "steps": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",

13
    "execution_context": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"

14
  }

15
}

Fetch a single execution

fetch-a-single-execution page anchor
GET https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
FlowSidSID<FW>required
Not PII

The SID of the Flow with the Execution resource to fetch

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<FN>required
Not PII

The SID of the Execution resource to fetch.

Pattern: ^FN[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch ExecutionLink to code sample: Fetch Execution
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchExecution() {

11
  const execution = await client.studio.v2

12
    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .executions("FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .fetch();

15


16
  console.log(execution.sid);

17
}

18


19
fetchExecution();

Output

1
{

2
  "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "contact_channel_address": "+14155555555",

6
  "status": "ended",

7
  "context": {},

8
  "date_created": "2017-11-06T12:00:00Z",

9
  "date_updated": null,

10
  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

11
  "links": {

12
    "steps": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",

13
    "execution_context": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"

14
  }

15
}

Read a list of executions

read-a-list-of-executions page anchor
GET https://studio.twilio.com/v2/Flows/{FlowSid}/Executions

Execution resources are listed in reverse chronological order (most recent is first).

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
FlowSidSID<FW>required
Not PII

The SID of the Flow with the Execution resources to read.

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

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
DateCreatedFromstring<date-time>Optional
Not PII

Only show Execution resources starting on or after this ISO 8601(link takes you to an external page) date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

DateCreatedTostring<date-time>Optional
Not PII

Only show Execution resources starting before this ISO 8601(link takes you to an external page) date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

PageSizeintegerOptional
Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000
PageintegerOptional
Not PII

The page index. This value is simply for client state.

Minimum: 0
PageTokenstringOptional
Not PII

The page token. This is provided by the API.

Read ExecutionLink to code sample: Read Execution
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listExecution() {

11
  const executions = await client.studio.v2

12
    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .executions.list({ limit: 20 });

14


15
  executions.forEach((e) => console.log(e.sid));

16
}

17


18
listExecution();

Output

1
{

2
  "meta": {

3
    "previous_page_url": null,

4
    "next_page_url": null,

5
    "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",

6
    "page": 0,

7
    "first_page_url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",

8
    "page_size": 50,

9
    "key": "executions"

10
  },

11
  "executions": []

12
}
Read Executions Filtered by DateLink to code sample: Read Executions Filtered by Date
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listExecution() {

11
  const executions = await client.studio.v2

12
    .flows("FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .executions.list({

14
      dateCreatedFrom: new Date("2019-02-17 00:00:00"),

15
      dateCreatedTo: new Date("2019-02-18 00:00:00"),

16
      limit: 20,

17
    });

18


19
  executions.forEach((e) => console.log(e.sid));

20
}

21


22
listExecution();

Output

1
{

2
  "meta": {

3
    "previous_page_url": null,

4
    "next_page_url": null,

5
    "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",

6
    "page": 0,

7
    "first_page_url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",

8
    "page_size": 50,

9
    "key": "executions"

10
  },

11
  "executions": []

12
}

Update an Execution

update-an-execution page anchor
POST https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}

An active Execution can be updated to ended using the REST API. Once ended, subsequent widgets in the Flow are not processed, and any new events that Studio receives for that Execution are rejected.

(information)

Info

Attempting to end an Execution that is already in the ended state will fail with a 409 Conflict.

Path parameters

path-parameters-3 page anchor
Property nameTypeRequiredPIIDescription
FlowSidSID<FW>required
Not PII

The SID of the Flow with the Execution resources to update.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<FN>required
Not PII

The SID of the Execution resource to update.

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

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Statusenum<string>required
Not PII

The status of the Execution. Can only be ended.

Possible values:
activeended
End an Active ExecutionLink to code sample: End an Active Execution
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function updateExecution() {

11
  const execution = await client.studio.v2

12
    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .executions("FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .update({ status: "ended" });

15


16
  console.log(execution.sid);

17
}

18


19
updateExecution();

Output

1
{

2
  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

4
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

6
  "context": {},

7
  "contact_channel_address": "+14155555555",

8
  "status": "ended",

9
  "date_created": "2017-11-06T12:00:00Z",

10
  "date_updated": "2017-11-06T12:00:00Z",

11
  "links": {

12
    "steps": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",

13
    "execution_context": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"

14
  }

15
}

Delete an execution

delete-an-execution page anchor
DELETE https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}

Path parameters

path-parameters-4 page anchor
Property nameTypeRequiredPIIDescription
FlowSidSID<FW>required
Not PII

The SID of the Flow with the Execution resources to delete.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<FN>required
Not PII

The SID of the Execution resource to delete.

Pattern: ^FN[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete ExecutionLink to code sample: Delete Execution
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function deleteExecution() {

11
  await client.studio.v2

12
    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .executions("FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .remove();

15
}

16


17
deleteExecution();