Amigo is now Concurrence
Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Runs

List runs (framework + conversation)

get

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/sms/whatsapp/email/web/imessage — conversation runs only), status (live expands to running + paused), service_id (service UUIDs), and search (entity name, caller ID or phone number). Repeated filter values are ORed within each axis; axes combine with AND. Service filtering applies to conversation and live voice runs before pagination. Historical framework runs have no stored service attribution and are excluded when service_id is set. continuation_token is an opaque page cursor.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
sort_bystring[]OptionalDefault: []
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
service_idstring · uuid[] · max: 100Optional

Filter conversation and live voice runs by up to 100 service IDs. Historical framework runs have no stored service attribution and are excluded. Repeated values are ORed; combines with other filters using AND.

Default: []
searchstring · min: 1 · max: 200 · nullableOptional

Case-insensitive substring match on a conversation run's entity name, caller ID or phone number, applied before pagination. Framework runs carry none of these and are excluded when search is set. Combines with other filters using AND.

Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/runs
GET /v1/{workspace_id}/runs HTTP/1.1
Host: platform.api-us.concurrence.com
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
}

Run counts (framework + conversation)

get

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.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
Responses
200

Successful Response

application/json

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. dormant counts open conversations idle past their channel threshold, which are not live.

totalintegerRequired
liveintegerRequired
runningintegerRequired
pausedintegerRequired
completedintegerRequired
failedintegerRequired
timed_outintegerRequired
dormantintegerRequired
get/v1/{workspace_id}/runs/summary
GET /v1/{workspace_id}/runs/summary HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "total": 1,
  "live": 1,
  "running": 1,
  "paused": 1,
  "completed": 1,
  "failed": 1,
  "timed_out": 1,
  "dormant": 1,
  "by_status": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "by_kind": {
    "ANY_ADDITIONAL_PROPERTY": 1
  }
}

Get one run (framework or conversation) by run_id

get

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.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Responses
200

Successful Response

application/json

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.

run_idstring · uuidRequired
workspace_idstring · uuidRequired
kindstring · enumRequiredPossible values:
statusstring · enumRequiredPossible values:
channelstring · enum · nullableOptionalPossible values:
frameworkstring · enum · nullableOptionalPossible values:
entity_idstring · uuid · nullableOptional
service_idstring · uuid · nullableOptional
started_atstring · date-timeRequired
ended_atstring · date-time · nullableOptional
entity_namestring · nullableOptional
service_namestring · nullableOptional
caller_idstring · nullableOptional
phone_numberstring · nullableOptional
directionstring · nullableOptional
turn_countinteger · nullableOptional
completion_reasonstring · nullableOptional
source_call_sidstring · nullableOptional
source_conversation_idstring · uuid · nullableOptional
source_framework_run_idstring · uuid · nullableOptional
get/v1/{workspace_id}/runs/{run_id}
GET /v1/{workspace_id}/runs/{run_id} HTTP/1.1
Host: platform.api-us.concurrence.com
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 run's step-by-step trajectory

get

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).

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Responses
200

Successful Response

application/json
truncatedbooleanRequired
get/v1/{workspace_id}/runs/{run_id}/trajectory
GET /v1/{workspace_id}/runs/{run_id}/trajectory HTTP/1.1
Host: platform.api-us.concurrence.com
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
}

Send operator guidance to a live run

post

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.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Body

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).

operator_idstring · uuidRequired
messagestring · min: 1 · max: 5000Required
Responses
200

Successful Response

application/json
statusstring · enumRequired

Delivery status

Possible values:
run_idstring · uuidRequired

Run the guidance was sent to

post/v1/{workspace_id}/runs/{run_id}/guidance
POST /v1/{workspace_id}/runs/{run_id}/guidance HTTP/1.1
Host: platform.api-us.concurrence.com
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"
}

Take over a live run as operator

post

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, or if the operator has no phone number configured. For voice, Twilio dials the operator's phone and the response carries the resulting conference/participant SIDs.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Body
operator_idstring · uuidRequired
modestring · enumOptionalDefault: takeoverPossible values:
Responses
200

Successful Response

application/json
run_idstring · uuidRequired
modestring · enumRequiredPossible values:
participant_call_sidstring · nullableOptional
conference_sidstring · nullableOptional
post/v1/{workspace_id}/runs/{run_id}/takeover
POST /v1/{workspace_id}/runs/{run_id}/takeover HTTP/1.1
Host: platform.api-us.concurrence.com
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 taken-over run back to the agent

post

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.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Body
operator_idstring · uuidRequired
Responses
200

Successful Response

application/json
run_idstring · uuidRequired
successbooleanRequired
post/v1/{workspace_id}/runs/{run_id}/handback
POST /v1/{workspace_id}/runs/{run_id}/handback HTTP/1.1
Host: platform.api-us.concurrence.com
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 the next turn on a non-voice run under takeover

post

Stage an operator-authored reply for a NON-voice run (sms/whatsapp/email/web/imessage) 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).

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Body
operator_idstring · uuidRequired
textstring · min: 1 · max: 4000Required
Responses
200

Successful Response

application/json
run_idstring · uuidRequired
stagedbooleanRequired
post/v1/{workspace_id}/runs/{run_id}/authored-turn
POST /v1/{workspace_id}/runs/{run_id}/authored-turn HTTP/1.1
Host: platform.api-us.concurrence.com
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 an operator between listen and takeover on a live run

post

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.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Body
operator_idstring · uuidRequired
participant_call_sidstring · max: 64Required
modestring · enumRequiredPossible values:
Responses
200

Successful Response

application/json
run_idstring · uuidRequired
modestring · enumRequiredPossible values:
post/v1/{workspace_id}/runs/{run_id}/switch-mode
POST /v1/{workspace_id}/runs/{run_id}/switch-mode HTTP/1.1
Host: platform.api-us.concurrence.com
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"
}
PreviousAgent Runs
NextMemory Dimensions

Last updated

Was this helpful?