> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# orca runs

> List, inspect, tail, and cancel runs.

> **Last updated: 2026-09-06**

`orca runs` inspects and controls [runs](/concepts/runs), the individual executions of an agent. Starting a run is `orca run`, documented on [orca run and orca chat](/cli/reference/run-and-chat).

Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). Subcommands that take an optional `[id]` open a picker over the 10 most recent runs when the id is omitted in a terminal; in a pipe or script the id is required (exit code 2). Exit codes are listed on [Output and scripting](/cli/output-and-scripting).

## orca runs list

```bash theme={"dark"}
orca runs list [--agent <name>] [--limit <n>] [--offset <n>] [--all]
```

Lists recent runs. With `--agent` the request goes to that agent's own runs endpoint, so the paging total reflects only its runs.

| Flag             | Type    | Default | Description                                                        |
| ---------------- | ------- | ------- | ------------------------------------------------------------------ |
| `--agent <name>` | string  | none    | Only runs for this agent                                           |
| `--limit <n>`    | integer | `10`    | Page size                                                          |
| `--offset <n>`   | integer | `0`     | Page offset                                                        |
| `--all`          | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) |

```bash theme={"dark"}
orca runs list --agent researcher --all --json | jq -r '.[] | select(.status == "error") | .id'
```

Plain (piped) output is one tab-separated row per run: `id`, `agent`, `status`, `started`, `duration` (`-` while the run is still running). `--json` prints an array of run summaries (`id`, `subTask`, `status`, `startedAt`, `finishedAt`). A run status is one of `running`, `ok`, `error`, `cancelled`, or `interrupted`. When there are no runs, stdout stays empty and a hint goes to stderr.

## orca runs get

```bash theme={"dark"}
orca runs get [id]
```

Shows one run with its full event transcript. With `--json` the full run object is printed, including its `events`. The plain view prints `Run`, `Agent`, `Title`, `Status`, `Started`, and `Duration` (once finished), then one line per event, then a `Tokens` line that sums the run's `usage` events.

```bash theme={"dark"}
orca runs get "$RUN_ID" --json | jq '.events[] | select(.type == "tool_call") | .toolName'
```

## orca runs cancel

```bash theme={"dark"}
orca runs cancel [id]
```

Cancels an in-flight run. There is no confirmation prompt. A tail attached to the run ends with status `cancelled` and exit code 1.

```bash theme={"dark"}
orca runs cancel "$RUN_ID" --json
```

```json theme={"dark"}
{ "id": "3d0b7f1a-6c2e-4b8a-9f51-0e6a2c4d7b90", "cancelled": true }
```

## orca runs tail

```bash theme={"dark"}
orca runs tail [id]
```

Attaches to a run's event stream and follows it until the run reaches a terminal status. The stream replays buffered events first, so tailing a finished run prints its whole transcript. A dropped connection reconnects with backoff and skips events already delivered, so nothing prints twice; a rejected subscription (bad key, unknown run) fails immediately.

In a terminal the tail renders a live transcript with a final status line (status, run id, elapsed time, token usage). When stdout is a pipe, each event is one plain text line: assistant text as is, `tool <name> <input>` for a call, its result indented beneath it (prefixed `error` when the tool failed), `error: <message>` for run errors, and progress or result messages; `usage` events never print. In both non-terminal modes a `run <id> finished: <status>` line goes to stderr.

With `--json` every run event is written to stdout as one JSON object per line (NDJSON). Each line has a `type` of `progress`, `result`, `error`, `assistant`, `tool_call`, `tool_result`, or `usage`, plus whichever of `message`, `ts`, `toolCallId`, `toolName`, `input`, `output`, `isError`, and `usage` apply to that type. A `usage` object carries `inputTokens`, `outputTokens`, `cacheReadTokens`, and `cacheCreateTokens`.

```bash theme={"dark"}
orca runs tail "$RUN_ID" --json
```

```json theme={"dark"}
{"type":"assistant","message":"Looking at the release notes now."}
{"type":"tool_call","toolCallId":"call_1","toolName":"web_search","input":{"q":"orca releases"}}
{"type":"usage","usage":{"inputTokens":1200,"outputTokens":300}}
```

The exit code follows the run's terminal state: `0` for `ok`, `1` for `error`, `cancelled`, or `interrupted`. Ctrl-C detaches the tail only (exit code 130); the run keeps going server-side, and stderr prints the commands to reattach (`orca runs tail <id>`) or stop it (`orca runs cancel <id>`).

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>