Smart Agent Teams
EndpointsRuns

Get Run

Get one run, including its full transcript. Answers 404 `NOT_FOUND` when the run does not belong to this company.

GET
/api/companies/{company_id}/runs/{run_id}

Get one run, including its full transcript.

Answers 404 NOT_FOUND when the run does not belong to this company.

Authorization

HTTPBearer
headerAuthorizationBearer <token>

Path Parameters

run_id*Run Id
Formatuuid
company_id*Company Id
Formatuuid

Response Body

Successful Response

application/json
  1. response
agent_id*Agent Id
Formatuuid
cost_cents*Cost Cents
created_at*|null
ended_at*|null
error*string|null
heartbeat_at?|null
id*Id
Formatuuid
routine_id*|null
runner_id?string|null
started_at*|null
status*Status
summary*string|null
task_id*|null
tokens_in*Tokens In
tokens_out*Tokens Out
transcript*array<>|null
trigger*Trigger
curl -X GET "https://example.com/api/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",  "cost_cents": 0,  "created_at": "2019-08-24T14:15:22Z",  "ended_at": "2019-08-24T14:15:22Z",  "error": "string",  "heartbeat_at": "2019-08-24T14:15:22Z",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "routine_id": "f53c5ff7-cfb7-4f43-8b79-3421a01d8e2a",  "runner_id": "string",  "started_at": "2019-08-24T14:15:22Z",  "status": "string",  "summary": "string",  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",  "tokens_in": 0,  "tokens_out": 0,  "transcript": [    {}  ],  "trigger": "string"}

Expire Stale Runs POST

Fail running runs whose runner stopped reporting. A run expires when its last heartbeat (or start time) is older than the lease, `RUN_LEASE_SECONDS` (default 300). Expired runs become `failed`, their running agents move to `error`, and budgets are enforced as for any finished run. Returns the expired run ids as `{"expired": [...]}`. `POST /runs/claim` does this automatically before claiming.

Update Run PATCH

Progress report from the process executing the run. Any report refreshes the lease (`heartbeat_at`); `append_transcript` entries are added to the end of the transcript. Moving to a finished status (`succeeded`, `failed`, `cancelled`) stamps `ended_at`, sets a running agent back to `idle` (`error` after a failure) and enforces its monthly budget, pausing it with a `budget_override` approval when reached. Errors: 400 `RUN_FINISHED` (already finished), 400 `INVALID_STATE` (back to `queued`), 409 `RUN_LEASE_LOST` (`runner_id` differs from the claiming runner). Publishes `run.updated`, plus `agent.updated` and `approval.created` as needed.