On this page
Runs
A run is one execution of a published agent: a phone call, a cloud task or a chat. For example, each call from the equipment-service agent to Alex has its own run ID. That ID links the conversation, executed path, business actions and usage. The run keeps the publication version it started with.
For example, a support task receives a ticket, classifies it and ends. A chat run instead stays open for messages from your application. A phone run connects to a recipient through your carrier. Start one below, or review an existing run.
Start a run
Call POST /api/v1/runs with a member or admin key and an Idempotency-Key. The 201 response means the run was accepted, not that the task or call finished. Keep the returned run ID to follow execution. The run uses the current head unless you supply version. A test-only publication requires test: true, including after head promotion. You can supply string-valued metadata for business context.
| Channel | Body | What happens |
|---|---|---|
cloud · task | { channel: "cloud", agent_id, mode: "task", input } | The input is checked against the publication's input schema, becomes the agent's variables and its one user turn. The run ends with a result validated against the output schema. |
cloud · chat | { channel: "cloud", agent_id, mode: "chat", input } | A conversation: send each user turn with POST …/messages. It ends at the agent's end node, its turn limit or its idle timeout. |
phone | { channel: "phone", agent_id, to, from?, dynamic_variables } | An outbound call from one of your numbers. See Phone. |
A chat run
# Start a chat run: input fills variables; the conversation happens in messages.
POST /api/v1/runs
{ "channel": "cloud", "agent_id": "…", "mode": "chat", "input": { "customer_name": "Ada" } }
# Send the user's turn (Idempotency-Key required). 202: { "run_id": "…", "index": 0 }
POST /api/v1/runs/{run_id}/messages
{ "text": "Where is my order?" }
# The agent's reply arrives as a run.message event on GET /api/v1/runs/{run_id}/events.
Step-by-step samples in curl, TypeScript and Python are in Using the API.
Dynamic variables
Use {{variables}} in prompts, transitions, transfer numbers and voicemail messages to personalize each run—for example, {{contact_name}} and {{service_request_id}} for a service call. A phone run fills them from dynamic_variables (string values), and so does a browser test (POST /api/v1/test-sessions). A cloud chat run receives its initial values in input. Every required name must be supplied or have a defined source. Values can come from:
- the run's
dynamic_variables(orinput, for a chat test); - the flow's own defaults (
defaultDynamicVariables); - a value the call produces itself: an
extract_dynamic_variablesnode or a tool's response; - the runtime:
tenant_id,call_id,workflow_id,agent_idandsystem.channel.
If any name is left without a value, the run is refused before it dials. You get 400 invalid_request with details.reason: "missing_dynamic_variables", and the message names every missing variable at once. No run is created, so fix the body and send it again with a new Idempotency-Key.
curl -sS -X POST "${CUMULUS_API_URL}/api/v1/runs" \
-H "Authorization: Bearer $CUMULUS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d "$(jq -n --arg agent "$PHONE_AGENT_ID" \
'{channel: "phone", agent_id: $agent, to: "+14155550123", from: "+14155550100", dynamic_variables: {}}')" \
| jq '.error // {run_id, state}'
# 400, and no run is created:
# { "code": "invalid_request", "retryable": false, "outcome": "none",
# "message": "Flow references dynamic variables that were not supplied: business_name, customer_name",
# "details": { "reason": "missing_dynamic_variables" } }To see what an agent needs before you call, read the flow of its head publication. It is in GET /api/v1/agents/{agent_id}/publications/{version}, under plan.flow. This recipe lists the names it references, minus the ones it provides itself:
VERSION=$(curl -sS "${CUMULUS_API_URL}/api/v1/agents/$PHONE_AGENT_ID" \
-H "Authorization: Bearer $CUMULUS_API_KEY" | jq -r .head.version)
curl -sS "${CUMULUS_API_URL}/api/v1/agents/$PHONE_AGENT_ID/publications/$VERSION" \
-H "Authorization: Bearer $CUMULUS_API_KEY" \
| jq -r '.plan.flow as $flow
| ([$flow | .. | strings | scan("\{\{\\s*([^{}]+?)\\s*\}\}")[0]] | unique)
- ($flow.defaultDynamicVariables | keys)
- [$flow | .. | objects | select(.kind? == "extract_dynamic_variables") | .variables[]?.name]
- [$flow | .. | objects | (.responseVariables? // {}) | keys[]]
- ["tenant_id", "call_id", "workflow_id", "agent_id", "system.channel"]
| .[]'This scan helps find prompt placeholders. Validate the draft as well: validation checks required values in components and other settings that a text scan can miss. Publishing a new version can change the list. A flow may declare callContextVariables for configuration such as a transfer route. Those values come from defaults and admitted/startup context. A lookup can override them for its current account; a rejected lookup or an omitted replace_available output restores the call baseline while clearing account outputs. Model extraction cannot rewrite declared call configuration. During a call, an authenticated PATCH /api/v1/runs/{run_id} changes both the current value and its call baseline. Verification subject, expected answers and policy fields cannot be declared as preserved call configuration.
Test runs
"test": true marks a run as a test. It uses the same execution path, phone numbers and capacity as a live run. Test runs are excluded from customer webhooks and event triggers, and their usage is not billed. List test and live runs separately with GET /api/v1/runs?test=true (or false).
A test phone run still places a real call
Use a number you control as
towhile you test.
Lifecycle
state is the same on every channel: admitted, running, ending, completed, failed, cancelled, rejected, expired. A phone run also has phone_state for the call itself. When a run ends, outcome says how on four axes: transport (did the call connect), execution (did the agent finish), contact (human, voicemail or IVR) and the business result; disposition is a separate projection and may be absent. Read configured analysis fields for the conversation summary and tool receipts for the actual business result.
POST …/cancelends an active run and returns202with the run. A live call is hung up at once and the run becomescancelledwhen the call has ended. Repeating the request is safe.PATCH /api/v1/runs/{run_id}changes a live phone call's dynamic variables or metadata and returns a receipt:202while it is applied,200once settled.GET /api/v1/runsfilters byagent_id,channel,state, time (after,before),disposition,contact,successful,versionandtest.
Events
Run events record admission, state changes, node entries, chat messages, settled actions, recording and analysis updates, and completion in order. GET /api/v1/runs/{run_id}/events returns them as a JSON page or streams them live (format and resume); add ?progress=live to a stream to receive transcript and action-attempt progress. Read message text through the transcript endpoint and action attempts and receipts through GET …/effects.
Read run outputs
| Read | Returns |
|---|---|
| GET …/result | A cloud task's output object (state pending, ready, none or expired). |
| GET …/transcript | Every turn with its role and text; for calls, timing and interruptions. |
| GET …/recording | Recording state and, when available, a short-lived authorized playback URL. |
| GET …/analysis | Fields extracted from the completed transcript, with their state and supporting evidence. |
| GET …/effects | Each action the run took, its authorization decision and its receipts. |
| GET …/usage | What the run metered and cost. |
Capacity
Each channel has a limit of concurrent runs for your organization. GET /api/v1/runs/capacity returns each channel's limit and active runs. A run beyond the limit is refused with 429 rate_limited and details.reason: "capacity_exhausted"; nothing is created, so retry later with the same key.
Run API operations
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
POST /api/v1/runs | runs_create | member | Start a cloud task, chat or phone call from a published agent. The response confirms admission; follow the run to determine its outcome. test: true marks a run as a test; a phone run can still dial a real destination and invoke configured tools. |
GET /api/v1/runs | runs_list | viewer | List runs using agent, channel, state, time and outcome filters. |
GET /api/v1/runs/capacity | runs_capacity | viewer | Read each channel’s admission status, concurrent-run limit and active count. |
GET /api/v1/runs/{run_id} | runs_get | viewer | Read a run’s current state, pinned publication and recorded context. |
PATCH /api/v1/runs/{run_id} | runs_update | member | Change variables or metadata during an active phone call. Read the returned receipt to confirm when the change is applied. |
GET /api/v1/runs/{run_id}/updates/{update_id} | runs_update_get | viewer | Read the status and outcome of a live phone-run update. |
POST /api/v1/runs/{run_id}/cancel | runs_cancel | member | Cancel an active run. A phone call settles as cancelled after its media session ends. |
POST /api/v1/runs/{run_id}/messages | runs_send_message | member | Send a user turn to a cloud chat run. Read the reply through run events or the transcript. |
GET /api/v1/runs/{run_id}/events | runs_events | viewer | Read a page of run events or subscribe to server-sent events. Resume after the last sequence you processed. |
GET /api/v1/runs/{run_id}/effects | runs_effects | viewer | Read the run’s action decisions, send attempts and receipts. Check these records when an external action fails or its outcome is uncertain. |
GET /api/v1/runs/{run_id}/transcript | runs_transcript | viewer | Read the run’s conversation turns, including available timing and interruption information. |
GET /api/v1/runs/{run_id}/result | runs_result | viewer | Read a cloud task’s structured output. Check the result state before consuming the output. |
GET /api/v1/runs/{run_id}/recording | runs_recording | viewer | Check recording availability and obtain a short-lived playback URL when it is ready. |
GET /api/v1/runs/{run_id}/analysis | runs_analysis | viewer | Read post-run disposition, success assessment and extracted fields. Check the analysis state for readiness. |
GET /api/v1/runs/{run_id}/usage | runs_usage | viewer | Read measured usage, pricing and completeness for one run. |