Command Overview
beacon token-usage reads Beacon runtime events from the JSONL log and summarizes token usage, cost, models, sessions, runs, harnesses, and repositories.
Command syntax
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.How token attribution works
Beacon normalizes token telemetry from every runtime into one canonicalgen_ai.usage 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, andcache_creationdo not overlap, so a total isinput + output + cache_read + cache_creationwithout 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_usdreflects 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 and Claude Code runtime pages for details.
Examples
Show token usage from the default per-user endpoint log:Show local token usage
Print JSON
Filter by session
Bucket usage over time
Inspect a CI run
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
Endpoint dashboard
Explore endpoint runtime logs locally in a browser.
Endpoint inventory
See configured, detected, hook, and observed endpoint inventory.