Skip to main content

​
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
Use this command when you need a local report before opening the dashboard, sending diagnostics, or validating token attribution for a specific agent session.
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 canonical gen_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, 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

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 a machine-readable report:
Print JSON
Filter to one session and include per-step detail:
Filter by session
Group usage into hourly time buckets:
Bucket usage over time
Inspect a CI runtime log and filter to a run:
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.

​
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.

Endpoint dashboard

Explore endpoint runtime logs locally in a browser.

Endpoint inventory

See configured, detected, hook, and observed endpoint inventory.