> ## 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 stats and orca usage

> Tenant-wide activity statistics, per-agent breakdowns, hotspots, and usage over time.

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

`orca stats` reports a snapshot of activity for the tenant over a look-back window: totals, a per-agent breakdown, and hotspots. `orca usage` reports token, cost, and run usage over time, plus tool-call and sandbox meters; spend lives only there, because the stats totals carry no cost field. See [Billing](/concepts/billing) for how usage is priced.

Both commands accept the [global flags](/cli/reference/overview#global-flags) and take no positional arguments. A `--window <w>` value is a positive integer followed by `m` (minutes), `h` (hours), `d` (days), or `w` (weeks); the help text advertises `1h`, `24h`, `7d`, and `30d`. An invalid window fails with exit code 2 before any request is made. The default is `24h` for every `orca stats` view and `7d` for `orca usage`.

## orca stats

```bash theme={"dark"}
orca stats [--window <w>]
```

Fetches the summary for the window. In a terminal and with `--json` it also fetches the per-agent and hotspot views; if either of those requests fails the summary still prints. When stdout is a pipe only the summary is fetched.

| Flag           | Type   | Default | Description      |
| -------------- | ------ | ------- | ---------------- |
| `--window <w>` | string | `24h`   | Look-back window |

```bash theme={"dark"}
orca stats --window 7d --json | jq '.summary.totals'
```

Plain (piped) output is tab-separated key and value rows: `window`, `agents`, `sessions`, `liveSessions`, `runs`, `runningRuns`, `failedRuns`, `cancelledRuns`, `tokens`, `errorRate` (a fraction with four decimals), `p95RunDurationMs`, `runners`, `healthyRunners`. `--json` prints `{ "window", "summary", "agents", "hotspots" }`: `summary` is the server's summary record (`window`, `since`, `until`, `totals`, `sessionStatusCounts`, `runStatusCounts`, `runnerPool`), `agents` is the per-agent array (empty when unavailable), and `hotspots` is the hotspots record (`null` when unavailable). The terminal view shows a Stats panel (agents, live and total sessions, runs, running, failed, and cancelled counts when non-zero, tokens, error rate, p95 run duration, healthy runners out of total and active sessions when the runner pool reports), then the Agents table and the Hotspots panel described below.

Wherever a token count appears, it is the sum of input, output, cache-read, and cache-create tokens.

## orca stats agents

```bash theme={"dark"}
orca stats agents [--window <w>]
```

Shows the per-agent breakdown for the window. There are no page flags; the server's own limit applies.

| Flag           | Type   | Default | Description      |
| -------------- | ------ | ------- | ---------------- |
| `--window <w>` | string | `24h`   | Look-back window |

```bash theme={"dark"}
orca stats agents --window 30d
```

Plain (piped) output is one tab-separated row per agent: `name`, `runtime` (`-` when empty), `runs`, `failedRuns`, `tokens`, `lastActivityAt` (`-` when absent). `--json` prints the server response (`window`, `since`, `until`, `total`, `limit`, `offset`, `sort`, `agents`); each agent record carries `name`, `runtime`, `sessions`, `liveSessions`, `runningSessions`, `erroredSessions`, `runs`, `runningRuns`, `failedRuns`, `cancelledRuns`, `tokens`, `lastActivityAt`, and `p95RunDurationMs`. The terminal view is a table with `agent`, `runtime`, `runs`, `failed`, `tokens`, and `last active`; with no activity in the window it prints `No agent activity in this window.` on stderr.

## orca stats hotspots

```bash theme={"dark"}
orca stats hotspots [--window <w>]
```

Shows the top contributors in four lists: `tokenConsumers` (value in tokens), `failingAgents` (value in failures), `busyRunners` (value in sessions), and `longSessions` (value in minutes).

| Flag           | Type   | Default | Description      |
| -------------- | ------ | ------- | ---------------- |
| `--window <w>` | string | `24h`   | Look-back window |

```bash theme={"dark"}
orca stats hotspots --json | jq '.tokenConsumers[:3]'
```

Plain (piped) output is one tab-separated row per entry: list name, `kind`, `name`, `value`. `--json` prints the server response (`window`, `since`, `until`, and the four arrays; each entry has `kind`, `name`, `value`, and optionally `runtime`, `tokens`, `lastEventAt`). The terminal view is a Hotspots panel with a section per non-empty list; when every list is empty it prints `No hotspots in this window.` on stderr.

## orca usage

```bash theme={"dark"}
orca usage [--window <w>] [--days <n>] [--meter <kind>]
```

Fetches the bucketed time series for the window and, best-effort, the tool-call and sandbox meter totals; the meters are reported as unavailable on conductors that do not expose them. `--meter` picks which series is plotted and listed. Tool-call and sandbox meters are aggregate-only, so they appear as totals and cannot be chosen with `--meter` (exit code 2).

| Flag             | Type    | Default  | Description                                                                                               |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `--window <w>`   | string  | `7d`     | Look-back window                                                                                          |
| `--days <n>`     | integer | none     | Look-back window in days (same as `--window <n>d`); must be positive. `--window` wins when both are given |
| `--meter <kind>` | string  | `tokens` | Series to plot: `tokens`, `cost`, or `runs`                                                               |

```bash theme={"dark"}
orca usage --days 30 --meter cost
orca usage --window 24h --json | jq '.timeseries.buckets[] | [.start, .runs, .costCents] | @tsv' -r
```

Plain (piped) output is one tab-separated row per bucket: bucket start (`YYYY-MM-DD HH:MM`), the meter name, the meter value (total tokens, cost in dollars, or run count), and the bucket's cost in dollars to two decimals (empty when zero). `--json` prints `{ "window", "meter", "timeseries", "meters" }`: `timeseries` has `window`, `bucket`, `since`, `until`, and `buckets`, each with `start`, `end`, `runs`, `failedRuns`, `runningRuns`, `tokens`, and `costCents`; `meters` has `window`, `totals` (`toolCalls`, `sandboxSeconds`), and `byProfile`, or is `null` when unavailable. The terminal view is a Usage panel with tokens, runs, failed runs and spend when non-zero, tool calls and sandbox seconds (or a `tool-call / sandbox unavailable` note), and a line chart of the chosen meter per bucket.

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