Skip to content Skip to navigation Skip to topbar

On this page

Execution Resource

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 or are kicked out of the Flow.

HTTP requests to Studio's REST API are protected with HTTP Basic authentication. To learn more about how Twilio handles authentication, please see our security documentation. You will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication.

(warning)

Warning

When triggering flows with the API, don't forget to also configure your Twilio Phone Number with your Studio Flow. If you don't configure the phone number, users won't be able to reply to your messages or call back to your IVR.

(error)

Deprecation Notice

The contact_sid property has been deprecated and will be replaced with a static placeholder value in the v1 API. Use contact_channel_address instead to uniquely track contacts. For the best experience and latest features, upgrade to the v2 API.

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

Execution Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<FN>

Optional

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

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

The SID of the Flow.

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

contact_sidSID<FC>

Optional

The SID of the Contact.

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

contact_channel_addressstring

Optional

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.

contextobject

Optional

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

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

Possible values:

activeended

date_createdstring<date-time>

Optional

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updatedstring<date-time>

Optional

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

urlstring<uri>

Optional

The absolute URL of the resource.

linksobject<uri-map>

Optional

The URLs of nested resources.

Create a new execution

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

(warning)

Warning

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

Path parameters

Property nameTypeRequiredPIIDescription

FlowSidSID<FW>required

The SID of the Excecution's Flow.

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Tostring<phone-number>required

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

Fromstring<phone-number>required

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.

Parametersobject

Optional

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 Execution

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 createExecution() {
11  const execution = await client.studio.v1
12    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .executions.create({
14      from: "+15017122661",
15      to: "+15558675310",
16    });
17
18  console.log(execution.sid);
19}
20
21createExecution();

Output

1{
2  "url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "sid": "FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6  "context": {},
7  "contact_sid": "FCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8  "contact_channel_address": "+18001234567",
9  "status": "active",
10  "date_created": "2015-07-30T20:00:00Z",
11  "date_updated": "2015-07-30T20:00:00Z",
12  "links": {
13    "steps": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",
14    "execution_context": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"
15  }
16}

Create an Execution with custom parameters

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 createExecution() {
11  const execution = await client.studio.v1
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
24createExecution();

Output

1{
2  "url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "sid": "FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "context": {},
7  "contact_sid": "FCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8  "contact_channel_address": "+18001234567",
9  "status": "active",
10  "date_created": "2015-07-30T20:00:00Z",
11  "date_updated": "2015-07-30T20:00:00Z",
12  "links": {
13    "steps": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",
14    "execution_context": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"
15  }
16}

Fetch a single execution

GET https://studio.twilio.com/v1/Flows/{FlowSid}/Executions/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

FlowSidSID<FW>required

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

The SID of the Execution resource to fetch.

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

Fetch Execution

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 fetchExecution() {
11  const execution = await client.studio.v1
12    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .executions("FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .fetch();
15
16  console.log(execution.sid);
17}
18
19fetchExecution();

Output

1{
2  "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "contact_sid": "FCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "contact_channel_address": "+14155555555",
7  "status": "ended",
8  "context": {},
9  "date_created": "2017-11-06T12:00:00Z",
10  "date_updated": null,
11  "url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12  "links": {
13    "steps": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",
14    "execution_context": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"
15  }
16}

Read a list of executions

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

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

Path parameters

Property nameTypeRequiredPIIDescription

FlowSidSID<FW>required

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

Property nameTypeRequiredPIIDescription

DateCreatedFromstring<date-time>

Optional

Only show Execution resources starting on or after this ISO 8601 date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

DateCreatedTostring<date-time>

Optional

Only show Execution resources starting before this ISO 8601 date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

Read Execution

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 listExecution() {
11  const executions = await client.studio.v1
12    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .executions.list({ limit: 20 });
14
15  executions.forEach((e) => console.log(e.sid));
16}
17
18listExecution();

Output

1{
2  "meta": {
3    "previous_page_url": null,
4    "next_page_url": null,
5    "url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",
6    "page": 0,
7    "first_page_url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",
8    "page_size": 50,
9    "key": "executions"
10  },
11  "executions": []
12}

Read Executions Filtered by Date

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 listExecution() {
11  const executions = await client.studio.v1
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
22listExecution();

Output

1{
2  "meta": {
3    "previous_page_url": null,
4    "next_page_url": null,
5    "url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",
6    "page": 0,
7    "first_page_url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions?PageSize=50&Page=0",
8    "page_size": 50,
9    "key": "executions"
10  },
11  "executions": []
12}

Update an Execution

POST https://studio.twilio.com/v1/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.

Path parameters

Property nameTypeRequiredPIIDescription

FlowSidSID<FW>required

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

The SID of the Execution resource to update.

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Statusenum<string>required

The status of the Execution. Can only be ended.

Possible values:

activeended

End an Active Execution

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 updateExecution() {
11  const execution = await client.studio.v1
12    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .executions("FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .update({ status: "ended" });
15
16  console.log(execution.sid);
17}
18
19updateExecution();

Output

1{
2  "url": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6  "context": {},
7  "contact_sid": "FCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8  "contact_channel_address": "+14155555555",
9  "status": "ended",
10  "date_created": "2017-11-06T12:00:00Z",
11  "date_updated": "2017-11-06T12:00:00Z",
12  "links": {
13    "steps": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Steps",
14    "execution_context": "https://studio.twilio.com/v1/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions/FNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Context"
15  }
16}

Delete an execution

DELETE https://studio.twilio.com/v1/Flows/{FlowSid}/Executions/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

FlowSidSID<FW>required

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

The SID of the Execution resource to delete.

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

Delete Execution

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 deleteExecution() {
11  await client.studio.v1
12    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .executions("FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .remove();
15}
16
17deleteExecution();