Skip to contentSkip to navigationSkip to topbar
Rate this page:
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(link takes you to an external page). 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(link takes you to an external page)

Execution Properties

execution-properties page anchor
Resource properties
sidtype: SID<FN>Not PII

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


account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the Execution resource.


flow_sidtype: SID<FW>Not PII

The SID of the Flow.


contact_sidtype: SID<FC>Not PII

The SID of the Contact.


contact_channel_addresstype: stringPII 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.


contexttype: objectPII 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.


statustype: enum<STRING>Not PII

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

Possible values:
activeended

date_createdtype: string<DATE TIME>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_updatedtype: string<DATE TIME>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.


urltype: string<URI>Not PII

The absolute URL of the resource.


linkstype: object<URI MAP>Not PII

The URLs of nested resources.


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.

Parameters

create-parameters page anchor
URI parameters
FlowSidtype: SID<FW>Not PII
Path Parameter

The SID of the Excecution's Flow.


Request body parameters
Totype: string<PHONE NUMBER>Not PII
Required

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


Fromtype: string<PHONE NUMBER>Not PII
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.


Parameterstype: objectNot 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.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.executions
_11
.create({to: '+15558675310', from: '+15017122661'})
_11
.then(execution => console.log(execution.sid));

Output

_16
{
_16
"url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"context": {},
_16
"contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"contact_channel_address": "+18001234567",
_16
"status": "active",
_16
"date_created": "2015-07-30T20:00:00Z",
_16
"date_updated": "2015-07-30T20:00:00Z",
_16
"links": {
_16
"steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16
"execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
_16
}
_16
}

Create an Execution with custom parameters

create-an-execution-with-custom-parameters page anchor

Create a new Execution with JSON data to be added to your flow's context. You will be able to access these parameters as variables inside your Studio flow.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13
.executions
_13
.create({parameters: {
_13
foo: 'bar'
_13
}, to: '+15558675310', from: '+15017122661'})
_13
.then(execution => console.log(execution.sid));

Output

_16
{
_16
"url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"context": {},
_16
"contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"contact_channel_address": "+18001234567",
_16
"status": "active",
_16
"date_created": "2015-07-30T20:00:00Z",
_16
"date_updated": "2015-07-30T20:00:00Z",
_16
"links": {
_16
"steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16
"execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
_16
}
_16
}


Fetch a single execution

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

URI parameters
FlowSidtype: SID<FW>Not PII
Path Parameter

The SID of the Flow with the Execution resource to fetch


Sidtype: SID<FN>Not PII
Path Parameter

The SID of the Execution resource to fetch.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.executions('FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(execution => console.log(execution.sid));

Output

_16
{
_16
"sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"contact_channel_address": "+14155555555",
_16
"status": "ended",
_16
"context": {},
_16
"date_created": "2017-11-06T12:00:00Z",
_16
"date_updated": null,
_16
"url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"links": {
_16
"steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16
"execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
_16
}
_16
}


Read a list of executions

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

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

URI parameters
FlowSidtype: SID<FW>Not PII
Path Parameter

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


DateCreatedFromtype: string<DATE TIME>Not PII
Query Parameter

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.


DateCreatedTotype: string<DATE TIME>Not PII
Query Parameter

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.


PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.executions
_11
.list({limit: 20})
_11
.then(executions => executions.forEach(e => console.log(e.sid)));

Output

_12
{
_12
"meta": {
_12
"previous_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12
"next_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=1",
_12
"url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12
"page": 0,
_12
"first_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12
"page_size": 50,
_12
"key": "executions"
_12
},
_12
"executions": []
_12
}

Read Executions Filtered by Date

read-executions-filtered-by-date page anchor

Executions can be filtered by the date they were created (30-day max range).

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.executions
_15
.list({
_15
dateCreatedFrom: new Date(Date.UTC(2019, 1, 17, 0, 0, 0)),
_15
dateCreatedTo: new Date(Date.UTC(2019, 1, 18, 0, 0, 0)),
_15
limit: 20
_15
})
_15
.then(executions => executions.forEach(e => console.log(e.sid)));

Output

_12
{
_12
"meta": {
_12
"previous_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12
"next_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=1",
_12
"url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12
"page": 0,
_12
"first_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12
"page_size": 50,
_12
"key": "executions"
_12
},
_12
"executions": []
_12
}


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.

URI parameters
FlowSidtype: SID<FW>Not PII
Path Parameter

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


Sidtype: SID<FN>Not PII
Path Parameter

The SID of the Execution resource to update.


Request body parameters
Statustype: enum<STRING>Not PII
Required

The status of the Execution. Can only be ended.

Possible values:
activeended
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.executions('FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({status: 'ended'})
_11
.then(execution => console.log(execution.sid));

Output

_16
{
_16
"url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"context": {},
_16
"contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"contact_channel_address": "+14155555555",
_16
"status": "ended",
_16
"date_created": "2017-11-06T12:00:00Z",
_16
"date_updated": "2017-11-06T12:00:00Z",
_16
"links": {
_16
"steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16
"execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
_16
}
_16
}


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

URI parameters
FlowSidtype: SID<FW>Not PII
Path Parameter

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


Sidtype: SID<FN>Not PII
Path Parameter

The SID of the Execution resource to delete.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.executions('FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();


Rate this page: