> ## Documentation Index
> Fetch the complete documentation index at: https://asymptotelabs-fix-postinstall-refresh-user-hooks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# beacon token-usage

> Report token usage and attribution from Beacon runtime logs

## Command Overview

`beacon token-usage` reads Beacon runtime events from the JSONL log and summarizes token usage, cost, models, sessions, runs, harnesses, and repositories.

```bash title="Command syntax" theme={null}
beacon token-usage [flags]
```

Use this command when you need a local report before opening the dashboard, sending diagnostics, or validating token attribution for a specific agent session.

<Note>
  In Beacon `v0.0.70`, token reporting moved from `beacon endpoint tokens` to the top-level `beacon token-usage` command. Update scripts, CI jobs, and runbooks that still invoke the old endpoint subcommand.
</Note>

## How token attribution works

Beacon normalizes token telemetry from every runtime into one canonical [`gen_ai.usage`](/telemetry-schema/normalization#usage-metadata) representation, then aggregates it locally from the runtime JSONL log. There are no per-harness token fields — a report over mixed runtimes uses the same vocabulary throughout.

A few rules shape how the numbers read:

* **Counts are kept disjoint.** `input_tokens`, `output_tokens`, `cache_read`, and `cache_creation` do not overlap, so a total is `input + output + cache_read + cache_creation` without double-counting. When a runtime reports prompt tokens inclusive of cache (Codex), Beacon subtracts the cached portion so the disjoint model holds.
* **Cost is runtime-reported only.** `cost_usd` reflects what the runtime emits. Beacon never derives cost from local pricing tables, so cost appears only for runtimes that report it.
* **Attribution depends on the metadata a runtime attaches.** Model, harness, repository, and run grouping work whenever those fields are present. Per-session grouping (`--session`, the session step tree) requires a session or conversation id on the usage signal.
* **Duplicate channels are de-duplicated.** When a runtime emits the same usage on more than one signal (Claude Code reports it on both logs and metrics), Beacon counts it once.

### Per-runtime coverage

| Runtime     | Tokens                                               | Cost                  | Per-session                            |
| ----------- | ---------------------------------------------------- | --------------------- | -------------------------------------- |
| Claude Code | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes                                    |
| Codex CLI   | input, output, cache read, reasoning                 | Not emitted by Codex  | No (metric carries no conversation id) |

`cost_usd` and `--session` detail are empty for Codex because Codex does not emit a cost signal or a conversation id on its usage metric — not a Beacon limitation. See the [Codex CLI](/runtimes/codex-cli#token-usage-and-cost) and [Claude Code](/runtimes/claude-code) runtime pages for details.

## Examples

Show token usage from the default per-user endpoint log:

```bash title="Show local token usage" theme={null}
beacon token-usage
```

Print a machine-readable report:

```bash title="Print JSON" theme={null}
beacon token-usage --json
```

Filter to one session and include per-step detail:

```bash title="Filter by session" theme={null}
beacon token-usage --session claude-session-123
```

Group usage into hourly time buckets:

```bash title="Bucket usage over time" theme={null}
beacon token-usage --bucket 1h
```

Inspect a CI runtime log and filter to a run:

```bash title="Inspect a CI run" theme={null}
beacon token-usage --log-path ./beacon-runtime.jsonl --run-id github/123456 --json
```

## Filters

Filters can be combined to narrow the report to a time range, model, agent harness, repository, session, or CI run.

| Flag                         | Description                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `--since <timestamp>`        | Only include events at or after this RFC3339 timestamp                         |
| `--until <timestamp>`        | Only include events at or before this RFC3339 timestamp                        |
| `--session <id>`             | Filter to one session and include per-step detail                              |
| `--model <name>`             | Filter by model name                                                           |
| `--harness <name>`           | Filter by harness name                                                         |
| `--repository <path-or-url>` | Filter by repository                                                           |
| `--run-id <id>`              | Filter by CI run ID. Bare run IDs and composite provider/run keys are accepted |
| `--bucket <duration>`        | Time-series bucket size, such as `1h` or `15m`                                 |
| `--top <count>`              | Limit each grouping to the top N entries. `0` keeps all entries                |

## Runtime Log Selection

By default, the command reads the per-user endpoint runtime log. Use `--system` for a system-mode endpoint, or `--log-path` when reading a copied runtime log or a CI session artifact.

| Flag                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--user`            | Use per-user endpoint paths. Enabled by default              |
| `--system`          | Use system endpoint paths                                    |
| `--log-path <path>` | Runtime JSONL log path. In CI, point this at the session log |
| `--json`            | Print the token usage report as JSON                         |

## Related

<Columns cols={2}>
  <Card title="Endpoint dashboard" icon="chart-line" href="/cli/dashboard">
    Explore endpoint runtime logs locally in a browser.
  </Card>

  <Card title="Endpoint inventory" icon="clipboard-list" href="/cli/endpoint-inventory">
    See configured, detected, hook, and observed endpoint inventory.
  </Card>
</Columns>