Guides
Runs and transcripts
A run is one task, executed once: answered directly, or, when it runs code, a shell or files, in a fresh sandbox of its own. Start it, follow it, read what it cost, and stop it if you need to.
The life of a run
| queued | Accepted and about to start; when it waits, waiting says why. |
| running | Working. Its transcript grows. |
| finished | It reached a result, in result. |
| failed | It ended without one; failure_reason says why, for example deadline exceeded. |
| stopped | A person, a key or a kill switch stopped it; stopped_by says who. |
The three end states are final: a run is never restarted. Each run has a deadline (deadlineSeconds, 900 by default) and a turn limit (maxTurns, 8 by default); past its deadline it is stopped, any sandbox it used is removed, and it fails as deadline exceeded.
Strict isolation
lane is sandbox and isolation_policy is strict. Strict is available on paid plans and can be part of an enterprise contract. Read it with GET /v1/tenant/run-isolation./v1/runsStart a run
Queues one task to run once. It is answered directly by the control plane, which runs no model code, unless lane is sandbox; an agent that holds workspace_start hands work that needs code, a shell, files or packages to a fresh sandbox of its own, as a child run. Name an agent to run it with that agent’s brief, model, tools and autonomy level; without one it is a bare task, governed as L0 with only record_finding. The run starts queued, then running, then ends in exactly one of finished, failed (with failure_reason) or stopped. A run under an engaged kill switch is refused (409 refused, naming the switch), and so is a deadline over the account’s maximum (3,600 seconds unless set otherwise) or an archived agent.
Body
- promptstringrequired
- The task: what should happen and what done looks like. 1 to 20,000 characters.
- agentIdstring (uuid)optional
- An agent on this account. The run uses the agent’s model, and naming a different model is refused.
- modelstringoptional
- For a bare run: claude-sonnet-5 (the default), claude-opus-5 or claude-haiku-4-5.
- maxTurnsintegeroptional
- The most model turns the run may take, 1 to 100. Default 8.
- deadlineSecondsintegeroptional
- How long the run may take before it is stopped and failed as deadline exceeded. At least 5; default 900.
- lanestringoptional
- direct (the default): answered by the control plane, which runs no model code. sandbox: the whole run in a fresh sandbox of its own, for work that needs code, a shell or files from the start. On an account under strict isolation every run is a sandbox run, and naming direct is refused (409); the run’s isolation_policy says which policy it ran under.
curl -X POST https://api.rykon.ai/v1/runs \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
"agentId": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"maxTurns": 8,
"deadlineSeconds": 900
}'{
"run": {
"id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"state": "queued",
"prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
"model": "claude-sonnet-5",
"max_turns": 8,
"deadline_seconds": 900,
"sandbox_driver": "kubernetes",
"sandbox_addr": null,
"created_by": "k7m2q9xd",
"created_at": "2026-10-30T14:02:11.408Z",
"started_at": null,
"deadline_at": null,
"finished_at": null,
"stopped_by": null,
"result": null,
"failure_reason": null,
"exit_code": null,
"num_turns": null,
"model_calls": 0,
"input_tokens": "0",
"output_tokens": "0",
"cost_usd": "0",
"reported_cost_usd": null,
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35"
}
}In the reference: Start a run
Following a run
Follow a run with a webhook, or by polling. Read its events with after set to the last event id you have, and read the run itself for its state. Every two seconds is plenty.
// Start a run, then read its transcript as it grows until it ends.
const base = 'https://api.rykon.ai/v1';
const headers = { Authorization: `Bearer ${process.env.RYKON_AI_KEY}`, 'Content-Type': 'application/json' };
type Run = { id: string; state: 'queued' | 'running' | 'finished' | 'failed' | 'stopped'; result: string | null; failure_reason: string | null; cost_usd: string };
type RunEvent = { id: string; kind: string; body: Record<string, unknown>; created_at: string };
const { run } = (await (await fetch(`${base}/runs`, {
method: 'POST',
headers,
body: JSON.stringify({ prompt: 'Summarise the attached notes in five bullet points.', maxTurns: 8 }),
})).json()) as { run: Run };
let after = '0';
let current = run;
while (current.state === 'queued' || current.state === 'running') {
await new Promise((r) => setTimeout(r, 2000));
const page = (await (await fetch(`${base}/runs/${run.id}/events?after=${after}`, { headers })).json()) as { events: RunEvent[] };
for (const e of page.events) console.log(e.kind);
after = page.events.at(-1)?.id ?? after;
current = ((await (await fetch(`${base}/runs/${run.id}`, { headers })).json()) as { run: Run }).run;
}
console.log(current.state, current.result ?? current.failure_reason, `$${current.cost_usd}`);/v1/runs/{id}/eventsRead a run’s transcript
The run’s transcript as events in order: what the model said, the tools it called and their answers, calls waiting for a person, and the result. Read it in pages with after, passing the id of the last event you have; a run that is still running grows at the end. Anything shaped like a token or key is redacted before an event is stored.
Path parameters
- idstring (uuid)required
- The run's id. An id from another account answers 404, exactly like one that does not exist.
Query parameters
- afterstringoptional
- Only events after this event id. Default 0, the start.
- limitintegeroptional
- 1 to 1,000. Default 500.
curl "https://api.rykon.ai/v1/runs/1/events?after=0&limit=500" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"events": [
{
"id": "1",
"kind": "system/egress_gate",
"body": {
"waitedMs": 412
},
"created_at": "2026-10-30T14:02:13.902Z"
},
{
"id": "2",
"kind": "assistant",
"body": {
"message": {
"content": [
{
"type": "text",
"text": "Comparing the three quotes per unit."
}
]
}
},
"created_at": "2026-10-30T14:02:19.640Z"
},
{
"id": "3",
"kind": "tool/answer",
"body": {
"tool": "record_finding",
"state": "done"
},
"created_at": "2026-10-30T14:02:31.903Z"
},
{
"id": "4",
"kind": "result/success",
"body": {
"result": "Recorded: Northgate Supply, $4.18 per unit (quote 2 of 3).",
"num_turns": 3
},
"created_at": "2026-10-30T14:02:49.811Z"
}
]
}In the reference: Read a run’s transcript
Cost
A run carries its model_calls, input_tokens, output_tokens and cost_usd. Token counts and cost are decimal strings, so large numbers survive JSON intact. Every model call went through the AI gateway on your account's key, which enforces a daily spend ceiling before each call.
Streamed calls
cost_usd can read low for those runs. The gateway records the price; it reaches the run in a later release.Stopping
/v1/runs/{id}/stopStop a run
Stops a queued or running run. It makes no further model or tool call; any sandbox work it started is stopped too, its token stops working on the sandbox’s next request and the sandbox is removed. stopped is false when the run had already ended, which is not an error. To stop every run of an agent, or the whole account, engage a kill switch instead.
Path parameters
- idstring (uuid)required
- The run's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40/stop \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"run": {
"id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"state": "stopped",
"prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
"model": "claude-sonnet-5",
"max_turns": 8,
"deadline_seconds": 900,
"sandbox_driver": "kubernetes",
"sandbox_addr": "10.42.3.17",
"created_by": "k7m2q9xd",
"created_at": "2026-10-30T14:02:11.408Z",
"started_at": "2026-10-30T14:02:13.120Z",
"deadline_at": "2026-10-30T14:17:13.120Z",
"finished_at": "2026-10-30T14:02:49.877Z",
"stopped_by": "k7m2q9xd",
"result": null,
"failure_reason": null,
"exit_code": 0,
"num_turns": 3,
"model_calls": 3,
"input_tokens": "9412",
"output_tokens": "611",
"cost_usd": "0.024934",
"reported_cost_usd": null,
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35"
},
"stopped": true
}In the reference: Stop a run