runs

Start a run

Start a cloud task, chat or phone call from a published agent. The response confirms admission; follow the run to determine its outcome.

For a phone call, send {channel: "phone", agent_id, to, from, dynamic_variables} and optionally version. The request dials a real number, including with test: true; confirm the destination before calling. Test runs are excluded from billing, customer webhooks and event triggers.

Use an imported number for from, or omit it to use the publication’s telephony.from. Supply the flow’s required variables in dynamic_variables; missing inputs return missing_dynamic_variables.

Check these refusal reasons:

  • tenant_not_configured or tenant_disabled: ask Cumulus to configure capacity and open admission.
  • trunk_not_authorized: check that the caller ID and trunk are authorized.
  • capacity_exhausted: wait for concurrent-run capacity.

For cloud execution, send {channel: "cloud", agent_id, mode: "task" | "chat", input}. To chat with a phone agent without dialing, use cloud chat with test: true.

post/api/v1/runs

Request

  • Base URL: https://api.cumuluslabs.io
  • URL: https://api.cumuluslabs.io/api/v1/runs
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Request body

OR

Response

Admit a cloud or phone run of a publication (201; an idempotent replay returns 200)

owner_idstring required
environmentstring required
tenant_idstring uuid required
run_idstring uuid required
agent_idstring required
plan_schema_versioninteger required
channel'cloud' | 'phone' | 'web' required
mode'task' | 'chat' | 'background' | 'outbound' | 'inbound' required
state'admitted' | 'running' | 'ending' | 'completed' | 'failed' | 'cancelled' | 'rejected' | 'expired' required
phone_state'admitted' | 'preparing' | 'awaiting_sip' | 'dialing' | 'ringing' | 'active' | 'terminating' | 'ended' | 'rejected' | 'expired' | 'setup_failed' nullable required
dispositionstring nullable required
attempt_countinteger required
created_atstring date-time required
started_atstring date-time nullable required
ended_atstring date-time nullable required
versioninteger required
tostring nullable required
fromstring nullable required
duration_msinteger nullable required
metadataobject required
testboolean required
provider_keysobject

Changes