Runs

What is a Run?

A Run is a single task submitted to an agent. Each run:

Targets a named Profile (the agent’s definition)
Carries a SubTask (the work to do)
Produces a stream of RunEvents (progress, tool calls, responses)
Is assigned a unique runId and a sessionId

Multiple runs can share a session, but only one run executes per session at a time.

Submitting a Run

POST /api/runs
Content-Type: application/json

{
  "profile": "researcher",
  "title": "Q1 market analysis",
  "prompt": "Summarize the top AI agent frameworks released in Q1 2026.",
  "files": []
}

Response 202 Accepted:

{
  "runId": "run-f3a9b72c",
  "sessionId": "sess-a1b2c3d4-e5f6g7h8"
}

SubTask Schema

This is the shape of the payload accepted by POST /api/runs. Not every field is client-facing: pool names the workflow a run was launched from, automationId and automationAgentFor are set when a run is started by, or is itself, an automation agent (validated server-side against the caller’s own automations), automationName is a denormalized automation name for display, and contexts names context documents to seed a new session with.

type SubTask struct {
  ID                 string
  ParentID           string
  Profile            string
  SessionID          string
  Title              string
  Prompt             string
  Files              []string
  Pool               string
  AutomationID       string
  AutomationAgentFor string
  AutomationName     string
  Contexts           []string
}

Streaming Events (SSE)

Once you have a runId, open an SSE stream:

curl -N https://api.orcapods.ai/api/runs/run-f3a9b72c/stream \
  -H 'Accept: text/event-stream'

The conductor streams RunEvent objects as Server-Sent Events. Events are replayed for late subscribers (the conductor buffers the run’s event log).

RunEvent Types

Every event in the stream is a JSON object with a type field. The types below are the common ones; the list is not exhaustive and may grow.

`progress`

Lifecycle milestones emitted by the runner and conductor.

{
  "type": "progress",
  "message": "Starting run...",
  "ts": "2026-04-25T10:00:00Z"
}

`session_init`

Runtime-native conversation handle emitted once per run when the sidecar reports it. The conductor preserves it as runtimeSessionId; UIs can ignore this event unless they need to correlate an Orca session with a Claude SDK session_id or Codex thread_id.

{
  "type": "session_init",
  "runtimeSessionId": "sdk-session-or-thread-id",
  "ts": "2026-04-25T10:00:01Z"
}

`assistant`

A text response from the LLM.

{
  "type": "assistant",
  "message": "Based on my research, the top frameworks are...",
  "ts": "2026-04-25T10:00:02Z"
}

`tool_call`

The agent is invoking a tool.

{
  "type": "tool_call",
  "toolCallId": "call_abc123",
  "toolName": "web_search",
  "input": { "query": "AI agent frameworks 2026", "max_results": 5 },
  "ts": "2026-04-25T10:00:03Z"
}

`tool_result`

The result of a tool invocation.

{
  "type": "tool_result",
  "toolCallId": "call_abc123",
  "toolName": "web_search",
  "output": { "results": [...] },
  "isError": false,
  "ts": "2026-04-25T10:00:04Z"
}

`usage`

Token usage reported by the LLM provider.

{
  "type": "usage",
  "usage": {
    "inputTokens": 1240,
    "outputTokens": 380,
    "cacheReadTokens": 800,
    "cacheCreateTokens": 440
  },
  "ts": "2026-04-25T10:00:10Z"
}

`result`

The final answer produced by the agent. Signals that the run is complete.

{
  "type": "result",
  "message": "1. LangGraph 2.0\n2. Orca\n3. AutoGen v3",
  "ts": "2026-04-25T10:00:11Z"
}

`error`

An unrecoverable error during the run.

{
  "type": "error",
  "message": "LLM provider returned 429: rate limit exceeded",
  "ts": "2026-04-25T10:00:05Z"
}

`thinking`

Provider-exposed reasoning text or summaries, when the underlying model returns any. Providers do not expose private chain of thought; this is only the display-safe content their SDKs return.

{
  "type": "thinking",
  "message": "Comparing the frameworks by GitHub activity first...",
  "ts": "2026-04-25T10:00:01Z"
}

`capability_span`

A bounded, redacted event describing one stage of a capability action, emitted while the agent works through a capability challenge (see POST /api/capabilities/discover and the related capabilities endpoints).

`capability_decision`

The durable, terminal human decision for one capability challenge and operation.

`capability_context_savings`

An estimated, non-provider usage comparison for a capability action.

Complete Event Sequence

A typical run produces events in this order:

progress    "Starting run..."
progress    "Session ready"
assistant   (first token stream begins)
tool_call   web_search { query: "..." }
tool_result web_search { results: [...] }
assistant   (continues writing)
tool_call   web_extract { urls: [...] }
tool_result web_extract { content: "..." }
assistant   (final answer)
result      "Final answer: ..."
usage       { inputTokens: 1240, outputTokens: 380 }

Consuming Events in TypeScript

const BASE = "https://api.orcapods.ai";
const apiKey = process.env.ORCA_API_KEY ?? "ao_..."; // Tenant API key (Settings, API Keys)
const authHeaders = {
  Authorization: `Bearer ${apiKey}`,
};

type RunEvent = { type: string; message?: string };

function parseSSEBlock(block: string): RunEvent | undefined {
  const data = block
    .split("\n")
    .filter((line) => line.startsWith("data:"))
    .map((line) => line.slice(5).trimStart())
    .join("\n");
  return data ? JSON.parse(data) : undefined;
}

async function* streamSSE(response: Response): AsyncGenerator<RunEvent> {
  if (!response.ok || !response.body) throw new Error("stream failed");

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    let boundary;
    while ((boundary = buffer.indexOf("\n\n")) !== -1) {
      const event = parseSSEBlock(buffer.slice(0, boundary));
      buffer = buffer.slice(boundary + 2);
      if (event) yield event;
    }
  }

  buffer += decoder.decode();
  if (buffer.trim()) {
    const event = parseSSEBlock(buffer);
    if (event) yield event;
  }
}

async function runAgent(profileName: string, prompt: string) {
  // 1. Submit run
  const { runId } = await fetch(`${BASE}/api/runs`, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...authHeaders },
    body: JSON.stringify({
      profile: profileName,
      title: "Task",
      prompt,
    }),
  }).then((r) => r.json());

  // 2. Stream events. Use fetch instead of EventSource when you need headers.
  const response = await fetch(`${BASE}/api/runs/${runId}/stream`, {
    headers: { Accept: "text/event-stream", ...authHeaders },
  });

  for await (const event of streamSSE(response)) {
    switch (event.type) {
      case "assistant":
        process.stdout.write(event.message ?? "");
        break;
      case "result":
        return event.message ?? "";
      case "error":
        throw new Error(event.message);
    }
  }

  return "";
}

const result = await runAgent("researcher", "What is LangGraph?");
console.log("\n\nFinal:", result);

Run Persistence

Runs are stored in an append-only JSONL log when AGENT_ORC_RUNS_DIR is set on the conductor:

AGENT_ORC_RUNS_DIR=/data/runs ./conductor

Each run gets one <runId>.jsonl file containing a header, event lines, and a finish line. Conductor replays these files on restart to reconstruct the in-memory run registry. Without AGENT_ORC_RUNS_DIR, runs are in-memory only and lost on conductor restart.

Listing & Inspecting Runs

# List recent runs
curl https://api.orcapods.ai/api/runs

# Get a specific run
curl https://api.orcapods.ai/api/runs/run-f3a9b72c

The GET /api/runs/{id} response includes the full event log for completed runs.

Run Status

Status	Description
`running`	Actively executing on a session
`ok`	`result` event received
`error`	`error` event received
`cancelled`	Explicitly cancelled
`interrupted`	Orphaned by conductor restart and closed by the boot reconciliation sweep

Stopping a Run

Use DELETE /api/runs/{runId} for normal, cooperative cancellation. It cancels the run context, aborts the runner stream and sidecar turn, and returns 204 No Content. If the run remains stuck, use POST /api/runs/{runId}/terminate as a last resort. Termination independently attempts to cancel any in-process run, waits up to two seconds for the session’s run claim to drain normally, then steals the claim only if it remains held. It also marks the durable run row as cancelled; a late completion cannot overwrite that status. The response reports which steps succeeded:

{
  "runId": "run-f3a9b72c",
  "cancelled": true,
  "sessionReleased": true,
  "claimStolen": false,
  "statusWritten": true,
  "sessionId": "sess-a1b2c3d4-e5f6g7h8",
  "warnings": []
}

Termination is idempotent and still attempts the durable status and session-release steps when the run is no longer in the current conductor’s in-memory registry. claimStolen: true identifies a claim that did not drain and had to be forcibly taken. Any warnings are stable codes rather than internal error details.

Get Started

Core Concepts

Guides

Runbooks

What is a Run?

Submitting a Run

SubTask Schema

Streaming Events (SSE)

RunEvent Types

`progress`

`session_init`

`assistant`

`tool_call`

`tool_result`

`usage`

`result`

`error`

`thinking`

`capability_span`

`capability_decision`

`capability_context_savings`

Complete Event Sequence

Consuming Events in TypeScript

Run Persistence

Listing & Inspecting Runs

Run Status

Stopping a Run

​What is a Run?

​Submitting a Run

​SubTask Schema

​Streaming Events (SSE)

​RunEvent Types

​progress

​session_init

​assistant

​tool_call

​tool_result

​usage

​result

​error

​thinking

​capability_span

​capability_decision

​capability_context_savings

​Complete Event Sequence

​Consuming Events in TypeScript

​Run Persistence

​Listing & Inspecting Runs

​Run Status

​Stopping a Run

What is a Run?

Submitting a Run

SubTask Schema

Streaming Events (SSE)

RunEvent Types

`progress`

`session_init`

`assistant`

`tool_call`

`tool_result`

`usage`

`result`

`error`

`thinking`

`capability_span`

`capability_decision`

`capability_context_savings`

Complete Event Sequence

Consuming Events in TypeScript

Run Persistence

Listing & Inspecting Runs

Run Status

Stopping a Run