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

queuedAccepted and about to start; when it waits, waiting says why.
runningWorking. Its transcript grows.
finishedIt reached a result, in result.
failedIt ended without one; failure_reason says why, for example deadline exceeded.
stoppedA 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

By default a run is answered directly and only code, shell and file work gets a sandbox. An owner or admin can set the account, or single roles, to Strict in Settings: every run then executes in a sandbox, 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.
POST/v1/runs

Start 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.

Needsruns:writeReturns201 Created

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.
POST/v1/runs
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
  }'
Response
201 Created
{
  "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.

TypeScript
// 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}`);
GET/v1/runs/{id}/events

Read 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.

Needsruns:readReturns200 OKPaged by after

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.
GET/v1/runs/{id}/events
curl "https://api.rykon.ai/v1/runs/1/events?after=0&limit=500" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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

A model answer that arrives as a stream is counted in tokens, but its price is not yet attached to the run, so cost_usd can read low for those runs. The gateway records the price; it reaches the run in a later release.

Stopping

POST/v1/runs/{id}/stop

Stop 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.

Needsruns:writeReturns200 OK

Path parameters

idstring (uuid)required
The run's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/runs/{id}/stop
curl -X POST https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40/stop \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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