Runs
Browse conversation runs and best-effort projected framework history, inspect structural trajectories, and control channel-aware operator takeover by run ID.
List Runs
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
[]50Successful Response
Validation Error
GET /v1/{workspace_id}/runs HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"kind": "conversation",
"status": "running",
"channel": "voice",
"framework": "claude-agent-sdk",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"started_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"entity_name": "text",
"service_name": "text",
"caller_id": "text",
"phone_number": "text",
"direction": "text",
"turn_count": 1,
"completion_reason": "text",
"source_call_sid": "text",
"source_conversation_id": "123e4567-e89b-12d3-a456-426614174000",
"source_framework_run_id": "123e4567-e89b-12d3-a456-426614174000",
"takeover": {
"eligible": true,
"mode_options": [
"listen"
],
"reason": "text"
}
}
],
"has_more": true,
"continuation_token": null
}Authentication
Status Mapping
Example Request
Example Response
Error Responses
Runs Summary
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Aggregate run counts for the Runs page summary strip.
Honest workspace totals the paginated list cannot derive client-side (it only
holds the loaded page). by_status carries the full canonical breakdown
(incl. any status beyond the named convenience fields); by_kind splits
framework vs conversation. live = running + paused.
Validation Error
GET /v1/{workspace_id}/runs/summary HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"total": 1,
"live": 1,
"running": 1,
"paused": 1,
"completed": 1,
"failed": 1,
"timed_out": 1,
"by_status": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"by_kind": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}Get a Run
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
One item in the canonical unified Runs read model.
run_id is a dedicated UUID (not an overloaded call_sid / conversation_id);
the originating subsystem's ids are kept as source_* provenance fields so a
run can always be traced back to its channel/framework origin. Conversation runs
carry a channel and no framework; framework runs carry a framework and
no channel — enforced below.
Validation Error
GET /v1/{workspace_id}/runs/{run_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"kind": "conversation",
"status": "running",
"channel": "voice",
"framework": "claude-agent-sdk",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"started_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"entity_name": "text",
"service_name": "text",
"caller_id": "text",
"phone_number": "text",
"direction": "text",
"turn_count": 1,
"completion_reason": "text",
"source_call_sid": "text",
"source_conversation_id": "123e4567-e89b-12d3-a456-426614174000",
"source_framework_run_id": "123e4567-e89b-12d3-a456-426614174000",
"takeover": {
"eligible": true,
"mode_options": [
"listen"
],
"reason": "text"
}
}Get a Framework 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).
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Validation Error
GET /v1/{workspace_id}/runs/{run_id}/trajectory HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"steps": [
{
"seq": 1,
"kind": "text",
"actor": "text",
"state": "text",
"tool_name": "text",
"tool_input_summary": "text",
"tool_result_summary": "text",
"tool_succeeded": true,
"decision_from_state": "text",
"decision_to_state": "text",
"effective_at": "text"
}
],
"truncated": true
}Takeover Eligibility
Operator Takeover
Take Over a Run
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
takeoverPossible values: Successful Response
Validation Error
POST /v1/{workspace_id}/runs/{run_id}/takeover HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72
{
"operator_id": "123e4567-e89b-12d3-a456-426614174000",
"mode": "takeover"
}{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"mode": "listen",
"participant_call_sid": "text",
"conference_sid": "text"
}Hand a Run Back
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Validation Error
POST /v1/{workspace_id}/runs/{run_id}/handback HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"operator_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"success": true
}Author a Non-Voice Turn
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).
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Validation Error
POST /v1/{workspace_id}/runs/{run_id}/authored-turn HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68
{
"operator_id": "123e4567-e89b-12d3-a456-426614174000",
"text": "text"
}{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"staged": true
}Switch Mode
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Validation Error
POST /v1/{workspace_id}/runs/{run_id}/switch-mode HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 100
{
"operator_id": "123e4567-e89b-12d3-a456-426614174000",
"participant_call_sid": "text",
"mode": "listen"
}{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"mode": "listen"
}Mint a Browser-Audio Access Token
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Validation Error
POST /v1/{workspace_id}/runs/{run_id}/access-token HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"operator_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"token": "text",
"identity": "text",
"conference_sid": "text",
"connect_params": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}Send Guidance
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Operator guidance for a live run. operator_id is in the body because this
router is not under /operators/{operator_id} — it is bound to the authenticated
caller by _enforce_operator_identity (no impersonation).
Successful Response
Delivery status
Run the guidance was sent to
Validation Error
POST /v1/{workspace_id}/runs/{run_id}/guidance HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71
{
"operator_id": "123e4567-e89b-12d3-a456-426614174000",
"message": "text"
}{
"status": "delivered",
"run_id": "123e4567-e89b-12d3-a456-426614174000"
}Agent Forge CLI
Rate Limits
Last updated
Was this helpful?