CumulusDocs
Open Studio
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.

ChannelBodyWhat 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

Example
# 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 (or input, for a chat test);
  • the flow's own defaults (defaultDynamicVariables);
  • a value the call produces itself: an extract_dynamic_variables node or a tool's response;
  • the runtime: tenant_id, call_id, workflow_id, agent_id and system.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 to while 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 …/cancel ends an active run and returns 202 with the run. A live call is hung up at once and the run becomes cancelled when 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: 202 while it is applied, 200 once settled.
  • GET /api/v1/runs filters by agent_id, channel, state, time (after, before), disposition, contact, successful, version and test.

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

ReadReturns
GET …/resultA cloud task's output object (state pending, ready, none or expired).
GET …/transcriptEvery turn with its role and text; for calls, timing and interruptions.
GET …/recordingRecording state and, when available, a short-lived authorized playback URL.
GET …/analysisFields extracted from the completed transcript, with their state and supporting evidence.
GET …/effectsEach action the run took, its authorization decision and its receipts.
GET …/usageWhat 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

OperationMCP toolKey rolePurpose
POST /api/v1/runsruns_creatememberStart 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/runsruns_listviewerList runs using agent, channel, state, time and outcome filters.
GET /api/v1/runs/capacityruns_capacityviewerRead each channel’s admission status, concurrent-run limit and active count.
GET /api/v1/runs/{run_id}runs_getviewerRead a run’s current state, pinned publication and recorded context.
PATCH /api/v1/runs/{run_id}runs_updatememberChange 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_getviewerRead the status and outcome of a live phone-run update.
POST /api/v1/runs/{run_id}/cancelruns_cancelmemberCancel an active run. A phone call settles as cancelled after its media session ends.
POST /api/v1/runs/{run_id}/messagesruns_send_messagememberSend a user turn to a cloud chat run. Read the reply through run events or the transcript.
GET /api/v1/runs/{run_id}/eventsruns_eventsviewerRead a page of run events or subscribe to server-sent events. Resume after the last sequence you processed.
GET /api/v1/runs/{run_id}/effectsruns_effectsviewerRead 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}/transcriptruns_transcriptviewerRead the run’s conversation turns, including available timing and interruption information.
GET /api/v1/runs/{run_id}/resultruns_resultviewerRead a cloud task’s structured output. Check the result state before consuming the output.
GET /api/v1/runs/{run_id}/recordingruns_recordingviewerCheck recording availability and obtain a short-lived playback URL when it is ready.
GET /api/v1/runs/{run_id}/analysisruns_analysisviewerRead post-run disposition, success assessment and extracted fields. Check the analysis state for readiness.
GET /api/v1/runs/{run_id}/usageruns_usageviewerRead measured usage, pricing and completeness for one run.
Content version 8f4b0747Customer SDKMarkdown source
Runs · Cumulus developer docs