roasOSGet an agent run
Read one run: what started it, its caps, the approvals it is waiting on, and — once it is terminal — what it cost. Every brain run is read here: an ask, a skill run, a routine run.
Read one run: what started it, its caps, the approvals it is waiting on, and — once it is terminal — what it cost. Every brain run is read here: an ask, a skill run, a routine run.
Authorization
bearerAuth API key authentication. Use your API key as the bearer token: Authorization: Bearer roasos_sk_...
In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/agent-runs/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "data": { "schema_version": "agent-run@1", "kind": "agent_run", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "trigger": "chat", "skill_id": "3cd68bb3-8b7e-48be-8232-1b99b5b4b3aa", "conversation_id": "cc71b11a-25cd-4c2d-9950-df2cc38e3407", "max_credits": 0, "generation_spend_cap_credits": 0, "pricing_version": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "status": "quoted", "credits_reserved": 0, "credits_max": 0, "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992", "expires_at": "2019-08-24T14:15:22Z", "authorization": { "status": "auto_approved" } }}Ask the agent
Start one agent run without a browser. The agent plans, calls tools, and can start paid generations on its own up to the cap you set. Two caps govern the run and neither replaces the other. `max_credits` bounds what the run's own thinking may cost. `generation_spend_cap_credits` bounds what the run may spend on renders, voices and other paid work without asking a person — it defaults to 0, so a run you say nothing about can never charge you for a render. Both caps are bounded again by this API key's own spend policy, and the policy always wins. Send `quote_only: true` to see the ceiling for free; the ceiling is `max_credits + generation_spend_cap_credits`. Send the same body with the returned `quote_id` to run it. Confirming reserves the ceiling, and the unused part is refunded when the run ends, so you are never charged more than the number you saw. The run is asynchronous: read it at `/v1/agent-runs/{id}`. Anything the run could not auto-approve waits as a card in `pending_approvals`; approve it in roasOS, or decline it here.
Get agent run status
The light poll: the run id, its status, and when it last changed.