halton-meter report · Halton Meter Docs

LLM spend logging and cost monitoring from the local SQLite store — cost reports by project, by model, with period comparison and CSV/JSON export. Layout adapts to terminal width.

halton-meter report reads ~/.halton-meter/db.sqlite directly and prints a Rich-formatted cost report (by project, by model, or both) with optional period comparison and CSV/JSON export. The layout collapses columns based on terminal width so the report stays readable in a narrow split.

Synopsis

$ halton-meter report [--since|--from --to] [--by project|model] [--vs-previous] [--csv|--json] [--project <slug>]

Common invocations

~: common report calls

$ halton-meter report                           # last 30 days, all projects, both tables
$ halton-meter report --since 7d                # last 7 days
$ halton-meter report --from 2026-04-01 --to 2026-04-30
$ halton-meter report --project halton-meter
$ halton-meter report --by project             # only the by-project table
$ halton-meter report --by model               # only the by-model table
$ halton-meter report --vs-previous             # add Δ% vs the prior period of the same length
$ halton-meter report --csv                     # CSV to stdout
$ halton-meter report --json                    # JSON to stdout

--since accepts a bare integer (days) or a duration like 7d, 90d. --since is mutually exclusive with --from / --to.

A typical report

~: halton-meter report

$ halton-meter report --since 7d

halton-meter v0.1.24 · cost report · 2026-04-30 → 2026-05-07

✓ 3,142 requests across 5 projects · 7 models
✓ Tokens: 412,007 in · 2,180,453 out
✓ Total cost: $284.13

by project              requests        in        out          cost  avg latency  p95
────────────────────────────────────────────────────────────────────────────────────────
halton-meter                1,406   189,221   997,032    $132.77     11,204ms   28,113ms
billing                       712    81,503   411,889     $71.42      9,884ms   22,005ms
experiments                   401    52,118   289,114     $41.06     12,002ms   30,219ms

by model                requests        in        out          cost
────────────────────────────────────────────────────────────────────
claude-opus-4-7           1,888   223,011  1,567,002    $232.11
claude-sonnet-4-6           876   118,224   421,556     $36.78
claude-haiku-4-5            378    70,772   191,895      $5.24

Layout responsiveness

The report layout switches columns based on $COLUMNS (logic in daemon/halton_meter/report.py::_layout_for_width()):

Width	Columns shown
`>= 110`	All seven + 7-day trend sparkline
`90–109`	Drops the 7-day trend
`70–89`	Drops `p95` and trend
`< 70`	Drops `avg`, `p95`, and trend

Column meanings

requests: count of metered request rows in the window
in / out, input / output token totals
cost: sum of cost_usd_minor_units / 100_000, formatted as USD
avg latency: mean wall-clock latency in milliseconds
p95 latency: 95th-percentile latency
7d trend: rolling sparkline of daily request counts

Cost rows for which the model was unknown to the rate card show as — rather than $0.00. Run halton-meter recompute-costs after a rate-card update to backfill.

CSV and JSON export

--csv writes the report-style aggregation to stdout. For the per-request export (one row per captured call, with the column shape documented in SQLite schema), use the HTTP API:

$ curl -sS -OJ "http://127.0.0.1:8765/v1/projects/<slug>/requests.csv"

--json is the canonical machine-readable shape, preferred over CSV when feeding into another tool.

Other useful flags

Flag	Purpose
`--db <path>`	Read a different SQLite file. Useful for working on a copy without locking the live one.
`--config <path>`	Override `config.toml` for this invocation.
`--vs-previous`	Add a Δ% column comparing to the prior window of the same length.

To pair this machine with a workspace, run the cloud connect command once with a scoped token.

What's next

SQLite schema: what each column maps to on disk
halton-meter recompute-costs: rebuild costs after a rate-card change
Local HTTP API: programmatic alternative to report