Smart Agent Teams
EndpointsRuns

Update Run

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.

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

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.

Authorization

HTTPBearer
headerAuthorizationBearer <token>

Path Parameters

run_id*Run Id
Formatuuid
company_id*Company Id
Formatuuid

Request Body

application/json
  1. body

Reported by whatever executes runs (an adapter or runner process).

append_transcript?array<>
Default[]
cost_cents?|null
error?string|null
runner_id?|null
status?|null
summary?string|null
tokens_in?|null
tokens_out?|null

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 PATCH "https://example.com/api/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{  "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"}

Get Run GET

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

Cancel Run POST

Cancel a queued or running run. Equivalent to `PATCH /runs/{run_id}` with `status: cancelled` and no `runner_id`, so it works whichever runner holds the run. The agent's budget is enforced as for any finished run. Fails with 400 `RUN_FINISHED` if the run already finished.