Smart Agent Teams
EndpointsRuns

Cancel Run

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.

POST
/api/companies/{company_id}/runs/{run_id}/cancel

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.

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 POST "https://example.com/api/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"
{  "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"}

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.

Get Run Context GET

Get the same context `POST /runs/claim` returns, without claiming the run. Use it to inspect or re-run a run: the run with its transcript, the agent and its manager, the company brief, the task with its comments, the task's goal chain and project, and `lease_seconds`. Answers 404 `NOT_FOUND` for runs outside this company.