Twilio Studio Flows & Executions
When a customer should get a call or text from a Studio flow you already built, trigger it with their number and JSON parameters, then follow the run step by step: which widget it reached, the flow context it collected, and whether it ended. Also lists flows and their published revisions, and ends stuck executions.
Connect this API to an AI agent Browse all specs
What you can do with Twilio Studio Flows & Executions via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v2/Flows |
listFlows | List Studio flows with their status and revision |
| GET | /v2/Flows/{Sid} |
getFlow | Get a flow, including its JSON definition |
| GET | /v2/Flows/{Sid}/Revisions |
listFlowRevisions | List the saved revisions of a flow |
| GET | /v2/Flows/{Sid}/Revisions/{Revision} |
getFlowRevision | Get one revision of a flow |
| POST | /v2/Flows/{FlowSid}/Executions |
createExecution | Start the flow for a contact (outbound call or message) |
| GET | /v2/Flows/{FlowSid}/Executions |
listExecutions | List runs of a flow, optionally within a date range |
| GET | /v2/Flows/{FlowSid}/Executions/{Sid} |
getExecution | Get one run of a flow and its status |
| POST | /v2/Flows/{FlowSid}/Executions/{Sid} |
endExecution | End an active run (set status to ended) |
| GET | /v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Context |
getExecutionContext | Get the data a run has collected so far |
| GET | /v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Steps |
listExecutionSteps | List the widgets a run passed through |
| GET | /v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Steps/{Sid} |
getExecutionStep | Get one step of a run |
| GET | /v2/Flows/{FlowSid}/Executions/{ExecutionSid}/Steps/{StepSid}/Context |
getExecutionStepContext | Get the data captured at one step |
Authentication
accountSid_authToken
HTTP Basic
HTTP basic auth: your Twilio Account SID as the username and Auth Token as the password (or an API key SID and secret).
How to get a credential
- Sign in to the Twilio Console (console.twilio.com).
- On the account dashboard, copy the Account SID (starts with
AC) and reveal the Auth Token. - Safer option: open Account > API keys & tokens, click Create API key (type Standard), and use the key SID (
SK...) as the username and the secret as the password.
Permissions used
Standard API keys and the Auth Token can call every operation below. Restricted API keys need these permissions:
| Permission | Operations |
|---|---|
| Studio Flows read | listFlows, getFlow, listFlowRevisions, getFlowRevision |
| Studio Executions read | listExecutions, getExecution, getExecutionContext, listExecutionSteps, getExecutionStep, getExecutionStepContext |
| Studio Executions write | createExecution, endExecution |
Common errors
- 401 Unauthorized (code 20003): wrong SID/token pair, or the API key belongs to another account. Re-copy both values.
- 403 Forbidden: a restricted API key lacks the Studio permission listed above.
- 400 Bad Request:
ToorFromis not in E.164 format,Fromis not a number on your account, orParametersis not valid JSON. - 404 Not Found: the flow SID (
FW...) or execution SID (FN...) does not exist in this account. - 429 Too Many Requests: slow down and retry with backoff.
Store the SID and secret as a VX Agents credential so they are never pasted into chat.
Usage guide
Setup
- Add a basic-auth credential: Twilio Account SID (or API key SID
SK...) as username, Auth Token (or API key secret) as password. - Call
listFlowsonce and pin the flow SID (FW...) you trigger most often, plus the Twilio number or Messaging Service SID you sendFrom.
Trigger a flow for a contact
listFlowsto find the flow; checkstatusispublished(drafts cannot run).- Show the user the flow name,
To,FromandParameters, and wait for confirmation: starting a flow places a real call or sends real messages and costs money. createExecutionwithTo(E.164, e.g.+14155550100),From(your Twilio number orMG...Messaging Service SID) and optionalParametersas a JSON string, e.g.{"appointment_time":"3pm"}. Inside the flow these appear as{{flow.data.appointment_time}}.- Keep the returned execution SID (
FN...).
Follow a run
getExecutionforstatus(activeorended).listExecutionStepsto see which widgets ran and the transitions taken (e.g.incomingMessage,noMatch).getExecutionContextfor everything collected so far (replies, HTTP widget results,flow.data);getExecutionStepContextfor the data at one widget.- A run stuck waiting for a reply can be ended with
endExecutionandStatus=ended(confirm with the user first).
Review history
listExecutionswithDateCreatedFrom/DateCreatedTo(ISO 8601) to audit recent runs of a flow.listFlowRevisions/getFlowRevisionto see what changed between published versions.
Good to know
- Bodies are form-encoded;
Parametersmust be a JSON string. - A contact can only be in one active execution of a flow at a time; if a new trigger fails for that reason, check
listExecutionsand end the old run first. - Lists are paged with
PageSize; followmeta.next_page_url. - This spec cannot create, edit or delete flows, or delete executions.
Source: Twilio Studio REST API v2 reference (https://www.twilio.com/docs/studio/rest-api/v2), checked 2026-10-21.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Twilio Studio Flows & Executions” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.