> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/api-reference/readme/platform/runs.md).

# Runs

## List runs (framework + conversation)

> Paginated, newest-first list of runs for the workspace behind the unified \`\`Run\`\` contract. Federates framework runs (Delta \`\`world.runs\`\` MV) and conversation runs (Lakebase \`\`world.conversations\`\`) at read time. Filter by \`\`kind\`\` (conversation / framework), \`\`channel\`\` (voice/text/sms/email/web — conversation runs only), and \`\`status\`\` (\`\`live\`\` expands to running + paused). \`\`continuation\_token\`\` is an opaque page cursor.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunsResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Run"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"RunsResponse"},"Run":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"kind":{"type":"string","enum":["conversation","framework"],"title":"Kind"},"status":{"type":"string","enum":["running","paused","completed","failed","timed_out"],"title":"Status"},"channel":{"anyOf":[{"type":"string","enum":["voice","text","sms","email","web"]},{"type":"null"}],"title":"Channel"},"framework":{"anyOf":[{"type":"string","enum":["claude-agent-sdk","openai-agents"]},{"type":"null"}],"title":"Framework"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Name"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Count"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"source_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Call Sid"},"source_conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Conversation Id"},"source_framework_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Framework Run Id"},"takeover":{"$ref":"#/components/schemas/TakeoverEligibility","description":"Channel-neutral takeover eligibility, derived from this run's own fields.\n\nA computed field (not a stored one) so eligibility is derived in ONE place and\ncan never drift across the reader's per-source builders — every ``Run``, however\nconstructed, exposes a consistent ``takeover`` on the wire + in OpenAPI.","readOnly":true}},"type":"object","required":["run_id","workspace_id","kind","status","started_at","takeover"],"title":"Run","description":"One item in the canonical unified Runs read model.\n\n``run_id`` is a dedicated UUID (not an overloaded ``call_sid`` / ``conversation_id``);\nthe originating subsystem's ids are kept as ``source_*`` provenance fields so a\nrun can always be traced back to its channel/framework origin. Conversation runs\ncarry a ``channel`` and no ``framework``; framework runs carry a ``framework`` and\nno ``channel`` — enforced below."},"TakeoverEligibility":{"properties":{"eligible":{"type":"boolean","title":"Eligible"},"mode_options":{"items":{"type":"string","enum":["listen","takeover"]},"type":"array","title":"Mode Options","default":[]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["eligible"],"title":"TakeoverEligibility","description":"Whether an operator can take a run over, and how — the channel-neutral signal the\nconsole keys on instead of a per-channel heuristic.\n\n``eligible`` = an operator may take this run over right now. ``mode_options`` = the\ntakeover modes valid for the run's channel (voice exposes ``listen`` + ``takeover``;\nenumerated asynchronous channels expose authored-turn ``takeover`` only).\n``reason`` = a short, human-facing explanation when NOT eligible (e.g.\n``\"run is not live\"``, ``\"channel not yet supported\"``), so the console can\nrender an honest disabled-state tooltip rather than a bare greyed button.\nServer-computed (see ``Run.takeover``) so eligibility rules live in one place and the\nconsole never re-derives them."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs":{"get":{"tags":["Runs"],"summary":"List runs (framework + conversation)","description":"Paginated, newest-first list of runs for the workspace behind the unified ``Run`` contract. Federates framework runs (Delta ``world.runs`` MV) and conversation runs (Lakebase ``world.conversations``) at read time. Filter by ``kind`` (conversation / framework), ``channel`` (voice/text/sms/email/web — conversation runs only), and ``status`` (``live`` expands to running + paused). ``continuation_token`` is an opaque page cursor.","operationId":"list_runs_v1__workspace_id__runs_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sort By"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"exclusiveMinimum":0,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"title":"Continuation Token"}},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"enum":["live","running","paused","completed","failed","timed_out"],"type":"string"},"default":[],"title":"Status"}},{"name":"kind","in":"query","required":false,"schema":{"type":"array","items":{"enum":["conversation","framework"],"type":"string"},"default":[],"title":"Kind"}},{"name":"channel","in":"query","required":false,"schema":{"type":"array","items":{"enum":["voice","text","sms","email","web"],"type":"string"},"default":[],"title":"Channel"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Run counts (framework + conversation)

> Aggregate counts for the workspace's runs behind the unified \`\`Run\`\` contract: \`\`total\`\`, \`\`live\`\` (running + paused), each canonical status, a full \`\`by\_status\`\` map, and \`\`by\_kind\`\` (conversation vs framework). Federates the Delta \`\`world.runs\`\` MV and Lakebase \`\`world.conversations\`\` with a cheap GROUP BY. Optional \`\`kind\`\` / \`\`channel\`\` filters mirror the list; a \`\`channel\`\` filter restricts to conversation runs.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunsSummaryResponse":{"properties":{"total":{"type":"integer","title":"Total"},"live":{"type":"integer","title":"Live"},"running":{"type":"integer","title":"Running"},"paused":{"type":"integer","title":"Paused"},"completed":{"type":"integer","title":"Completed"},"failed":{"type":"integer","title":"Failed"},"timed_out":{"type":"integer","title":"Timed Out"},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status"},"by_kind":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Kind"}},"type":"object","required":["total","live","running","paused","completed","failed","timed_out","by_status","by_kind"],"title":"RunsSummaryResponse","description":"Aggregate run counts for the Runs page summary strip.\n\nHonest workspace totals the paginated list cannot derive client-side (it only\nholds the loaded page). ``by_status`` carries the full canonical breakdown\n(incl. any status beyond the named convenience fields); ``by_kind`` splits\nframework vs conversation. ``live`` = running + paused."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/summary":{"get":{"tags":["Runs"],"summary":"Run counts (framework + conversation)","description":"Aggregate counts for the workspace's runs behind the unified ``Run`` contract: ``total``, ``live`` (running + paused), each canonical status, a full ``by_status`` map, and ``by_kind`` (conversation vs framework). Federates the Delta ``world.runs`` MV and Lakebase ``world.conversations`` with a cheap GROUP BY. Optional ``kind`` / ``channel`` filters mirror the list; a ``channel`` filter restricts to conversation runs.","operationId":"runs_summary_v1__workspace_id__runs_summary_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"kind","in":"query","required":false,"schema":{"type":"array","items":{"enum":["conversation","framework"],"type":"string"},"title":"Kind"}},{"name":"channel","in":"query","required":false,"schema":{"type":"array","items":{"enum":["voice","text","sms","email","web"],"type":"string"},"title":"Channel"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get one run (framework or conversation) by run\_id

> Resolve a single run by its channel-neutral \`\`run\_id\`\` and return the canonical \`\`Run\`\` — at any status (live, completed, failed, timed out). Federates the Delta \`\`world.runs\`\` MV (framework runs), Lakebase \`\`world.conversations\`\` (conversation runs), and the live-voice registry, matched by \`\`run\_id\`\` and scoped to the workspace. Use the returned \`\`kind\`\` / \`\`channel\`\` / \`\`source\_\*\`\` fields to open the channel-appropriate detail (voice call, text conversation, framework trace). 404 if the run does not exist in this workspace.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"Run":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"kind":{"type":"string","enum":["conversation","framework"],"title":"Kind"},"status":{"type":"string","enum":["running","paused","completed","failed","timed_out"],"title":"Status"},"channel":{"anyOf":[{"type":"string","enum":["voice","text","sms","email","web"]},{"type":"null"}],"title":"Channel"},"framework":{"anyOf":[{"type":"string","enum":["claude-agent-sdk","openai-agents"]},{"type":"null"}],"title":"Framework"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Name"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Count"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"source_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Call Sid"},"source_conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Conversation Id"},"source_framework_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Framework Run Id"},"takeover":{"$ref":"#/components/schemas/TakeoverEligibility","description":"Channel-neutral takeover eligibility, derived from this run's own fields.\n\nA computed field (not a stored one) so eligibility is derived in ONE place and\ncan never drift across the reader's per-source builders — every ``Run``, however\nconstructed, exposes a consistent ``takeover`` on the wire + in OpenAPI.","readOnly":true}},"type":"object","required":["run_id","workspace_id","kind","status","started_at","takeover"],"title":"Run","description":"One item in the canonical unified Runs read model.\n\n``run_id`` is a dedicated UUID (not an overloaded ``call_sid`` / ``conversation_id``);\nthe originating subsystem's ids are kept as ``source_*`` provenance fields so a\nrun can always be traced back to its channel/framework origin. Conversation runs\ncarry a ``channel`` and no ``framework``; framework runs carry a ``framework`` and\nno ``channel`` — enforced below."},"TakeoverEligibility":{"properties":{"eligible":{"type":"boolean","title":"Eligible"},"mode_options":{"items":{"type":"string","enum":["listen","takeover"]},"type":"array","title":"Mode Options","default":[]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["eligible"],"title":"TakeoverEligibility","description":"Whether an operator can take a run over, and how — the channel-neutral signal the\nconsole keys on instead of a per-channel heuristic.\n\n``eligible`` = an operator may take this run over right now. ``mode_options`` = the\ntakeover modes valid for the run's channel (voice exposes ``listen`` + ``takeover``;\nenumerated asynchronous channels expose authored-turn ``takeover`` only).\n``reason`` = a short, human-facing explanation when NOT eligible (e.g.\n``\"run is not live\"``, ``\"channel not yet supported\"``), so the console can\nrender an honest disabled-state tooltip rather than a bare greyed button.\nServer-computed (see ``Run.takeover``) so eligibility rules live in one place and the\nconsole never re-derives them."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}":{"get":{"tags":["Runs"],"summary":"Get one run (framework or conversation) by run_id","description":"Resolve a single run by its channel-neutral ``run_id`` and return the canonical ``Run`` — at any status (live, completed, failed, timed out). Federates the Delta ``world.runs`` MV (framework runs), Lakebase ``world.conversations`` (conversation runs), and the live-voice registry, matched by ``run_id`` and scoped to the workspace. Use the returned ``kind`` / ``channel`` / ``source_*`` fields to open the channel-appropriate detail (voice call, text conversation, framework trace). 404 if the run does not exist in this workspace.","operationId":"get_run_v1__workspace_id__runs__run_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get a framework run's step-by-step trajectory

> Ordered structural steps (perception / decision / tool / completion) of a FRAMEWORK run, read from the durable Delta trace source by the run's correlation id. 404 if the run does not exist in this workspace; 409 if the run is a conversation run (use \`\`/conversations/{id}\`\` for per-turn detail).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunTrajectoryResponse":{"properties":{"steps":{"items":{"$ref":"#/components/schemas/TrajectoryStep"},"type":"array","title":"Steps"},"truncated":{"type":"boolean","title":"Truncated"}},"type":"object","required":["steps","truncated"],"title":"RunTrajectoryResponse"},"TrajectoryStep":{"properties":{"seq":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seq"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"},"actor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"tool_input_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Input Summary"},"tool_result_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Result Summary"},"tool_succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tool Succeeded"},"decision_from_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision From State"},"decision_to_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision To State"},"effective_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective At"}},"type":"object","title":"TrajectoryStep","description":"One structural step of a framework run's trajectory. Fields are best-effort\n(only those the step actually carries are present), all optional, and free ``str``\nfor the same read-model resilience the ``Run`` descriptive fields use."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}/trajectory":{"get":{"tags":["Runs"],"summary":"Get a framework run's step-by-step trajectory","description":"Ordered structural steps (perception / decision / tool / completion) of a FRAMEWORK run, read from the durable Delta trace source by the run's correlation id. 404 if the run does not exist in this workspace; 409 if the run is a conversation run (use ``/conversations/{id}`` for per-turn detail).","operationId":"get_run_trajectory_v1__workspace_id__runs__run_id__trajectory_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunTrajectoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Send operator guidance to a live run

> Send text guidance to the agent handling a LIVE run, addressed by the channel-neutral \`\`run\_id\`\`. The agent incorporates it into its next response without the operator taking over. Requires \`\`admin\`\` (Operator:Update) and is bound to the caller's own operator identity (no impersonation). 404 if the run is not a live run in this workspace; 409 if its channel has no live guidance transport yet.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunGuidanceRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"message":{"type":"string","maxLength":5000,"minLength":1,"title":"Message"}},"type":"object","required":["operator_id","message"],"title":"RunGuidanceRequest","description":"Operator guidance for a live run. ``operator_id`` is in the body because this\nrouter is not under ``/operators/{operator_id}`` — it is bound to the authenticated\ncaller by ``_enforce_operator_identity`` (no impersonation)."},"RunGuidanceResponse":{"properties":{"status":{"type":"string","enum":["delivered","queued_no_subscriber","deduplicated","failed","unknown"],"title":"Status","description":"Delivery status"},"run_id":{"type":"string","format":"uuid","title":"Run Id","description":"Run the guidance was sent to"}},"type":"object","required":["status","run_id"],"title":"RunGuidanceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}/guidance":{"post":{"tags":["Runs"],"summary":"Send operator guidance to a live run","description":"Send text guidance to the agent handling a LIVE run, addressed by the channel-neutral ``run_id``. The agent incorporates it into its next response without the operator taking over. Requires ``admin`` (Operator:Update) and is bound to the caller's own operator identity (no impersonation). 404 if the run is not a live run in this workspace; 409 if its channel has no live guidance transport yet.","operationId":"send_run_guidance_v1__workspace_id__runs__run_id__guidance_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunGuidanceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunGuidanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Take over a live run as operator

> Register the caller's operator identity on a LIVE run and (in \`\`takeover\`\` mode) suspend the agent so the human drives; \`\`listen\`\` mode monitors without driving. Addressed by the channel-neutral \`\`run\_id\`\`. Requires \`\`admin\`\` (Operator:Update), bound to the caller's own operator identity (no impersonation). 404 if the run is not live in this workspace; 409 if its channel does not support live takeover yet. For voice, the response carries the conference/participant SIDs the console needs to attach browser audio.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunTakeoverRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","default":"takeover"}},"type":"object","required":["operator_id"],"title":"RunTakeoverRequest"},"RunTakeoverResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"},"participant_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Participant Call Sid"},"conference_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conference Sid"}},"type":"object","required":["run_id","mode"],"title":"RunTakeoverResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}/takeover":{"post":{"tags":["Runs"],"summary":"Take over a live run as operator","description":"Register the caller's operator identity on a LIVE run and (in ``takeover`` mode) suspend the agent so the human drives; ``listen`` mode monitors without driving. Addressed by the channel-neutral ``run_id``. Requires ``admin`` (Operator:Update), bound to the caller's own operator identity (no impersonation). 404 if the run is not live in this workspace; 409 if its channel does not support live takeover yet. For voice, the response carries the conference/participant SIDs the console needs to attach browser audio.","operationId":"take_over_run_v1__workspace_id__runs__run_id__takeover_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunTakeoverRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunTakeoverResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Hand a taken-over run back to the agent

> Release the caller's operator from a run they took over — the agent resumes. Addressed by \`\`run\_id\`\`. Requires \`\`admin\`\` (Operator:Update), bound to the caller's own operator identity. 404 if the run is not live in this workspace; 409 if its channel does not support live takeover yet.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunHandbackRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"}},"type":"object","required":["operator_id"],"title":"RunHandbackRequest"},"RunHandbackResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"success":{"type":"boolean","title":"Success"}},"type":"object","required":["run_id","success"],"title":"RunHandbackResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}/handback":{"post":{"tags":["Runs"],"summary":"Hand a taken-over run back to the agent","description":"Release the caller's operator from a run they took over — the agent resumes. Addressed by ``run_id``. Requires ``admin`` (Operator:Update), bound to the caller's own operator identity. 404 if the run is not live in this workspace; 409 if its channel does not support live takeover yet.","operationId":"hand_back_run_v1__workspace_id__runs__run_id__handback_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunHandbackRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunHandbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Author the next turn on a non-voice run under takeover

> Stage an operator-authored reply for a NON-voice run (text/sms/email/web) the caller has taken over. The agent-engine send-gate substitutes it for the agent's next outbound (exactly-once), so the caller receives the operator's words while the agent stays suspended. Repeatable — each call stages the next turn. Addressed by the channel-neutral \`\`run\_id\`\`. Requires \`\`admin\`\` (Operator:Update), bound to the caller's own operator identity (no impersonation). 404 if the run is not live in this workspace; 409 for voice (voice takeover drives the live audio leg — use the conference, not an authored turn).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunAuthoredTurnRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"text":{"type":"string","maxLength":4000,"minLength":1,"title":"Text"}},"type":"object","required":["operator_id","text"],"title":"RunAuthoredTurnRequest"},"RunAuthoredTurnResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"staged":{"type":"boolean","title":"Staged"}},"type":"object","required":["run_id","staged"],"title":"RunAuthoredTurnResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}/authored-turn":{"post":{"tags":["Runs"],"summary":"Author the next turn on a non-voice run under takeover","description":"Stage an operator-authored reply for a NON-voice run (text/sms/email/web) the caller has taken over. The agent-engine send-gate substitutes it for the agent's next outbound (exactly-once), so the caller receives the operator's words while the agent stays suspended. Repeatable — each call stages the next turn. Addressed by the channel-neutral ``run_id``. Requires ``admin`` (Operator:Update), bound to the caller's own operator identity (no impersonation). 404 if the run is not live in this workspace; 409 for voice (voice takeover drives the live audio leg — use the conference, not an authored turn).","operationId":"author_run_turn_v1__workspace_id__runs__run_id__authored_turn_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAuthoredTurnRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAuthoredTurnResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Switch an operator between listen and takeover on a live run

> Toggle the operator between \`\`listen\`\` (monitor) and \`\`takeover\`\` (drive) on a run they have already joined, addressed by the channel-neutral \`\`run\_id\`\`. For voice this mutes/unmutes the operator's conference participant. Requires \`\`admin\`\` (Operator:Update), bound to the caller's own operator identity (no impersonation). 404 if the run is not live in this workspace; 409 if its channel does not support live takeover yet.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunSwitchModeRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"participant_call_sid":{"type":"string","maxLength":64,"title":"Participant Call Sid"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"}},"type":"object","required":["operator_id","participant_call_sid","mode"],"title":"RunSwitchModeRequest"},"RunSwitchModeResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"}},"type":"object","required":["run_id","mode"],"title":"RunSwitchModeResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}/switch-mode":{"post":{"tags":["Runs"],"summary":"Switch an operator between listen and takeover on a live run","description":"Toggle the operator between ``listen`` (monitor) and ``takeover`` (drive) on a run they have already joined, addressed by the channel-neutral ``run_id``. For voice this mutes/unmutes the operator's conference participant. Requires ``admin`` (Operator:Update), bound to the caller's own operator identity (no impersonation). 404 if the run is not live in this workspace; 409 if its channel does not support live takeover yet.","operationId":"switch_run_mode_v1__workspace_id__runs__run_id__switch_mode_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSwitchModeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSwitchModeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Mint a browser-audio access token for an operator on a live run

> Generate the Twilio browser-audio credentials the console needs to attach the operator's WebRTC leg to a live run, addressed by \`\`run\_id\`\`. This is the media plane companion to \`\`/takeover\`\` (the control plane). Requires \`\`admin\`\` (Operator:Update), bound to the caller's own operator identity. 404 if the run is not live in this workspace; 409 if its channel has no browser-audio leg.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunAccessTokenRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"}},"type":"object","required":["operator_id"],"title":"RunAccessTokenRequest"},"RunAccessTokenResponse":{"properties":{"token":{"type":"string","title":"Token"},"identity":{"type":"string","title":"Identity"},"conference_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conference Sid"},"connect_params":{"additionalProperties":{"type":"string"},"type":"object","title":"Connect Params"}},"type":"object","required":["token","identity"],"title":"RunAccessTokenResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/runs/{run_id}/access-token":{"post":{"tags":["Runs"],"summary":"Mint a browser-audio access token for an operator on a live run","description":"Generate the Twilio browser-audio credentials the console needs to attach the operator's WebRTC leg to a live run, addressed by ``run_id``. This is the media plane companion to ``/takeover`` (the control plane). Requires ``admin`` (Operator:Update), bound to the caller's own operator identity. 404 if the run is not live in this workspace; 409 if its channel has no browser-audio leg.","operationId":"mint_run_access_token_v1__workspace_id__runs__run_id__access_token_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAccessTokenRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAccessTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/runs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.