What tokenstat counts, and how to read the numbers

tokenstat combines usage records from supported coding tools. Most are read from local files or databases. Cursor usage comes from a vendor connection. Antigravity IDE collection needs its app running.

It can collect supported usage even when you started the session outside tokenstat. Coverage depends on the records your tools retained. See supported tools.

Token totals

Reports separate four categories:

• Fresh input: input tokens outside the reported cache categories.
• Cache write: input recorded as being written to a cache. Where available, five-minute and one-hour writes are tracked separately for pricing.
• Cache read: input served from a cache.
• Output: tokens produced by the model.

These categories are normalized to avoid adding the same input twice. Providers differ in which categories they report and how they price them.

Cache reads can make up much of an agent's total because the model reuses context across requests. A large total including cache is different from the amount of new input and output. Reports show the split so you can compare them.

Estimated API value and actual charges

List-rate value estimates the API price of the recorded tokens. It helps compare model usage, but it is not an invoice.

Usage identified as subscription-covered is kept separate from metered API spend. Your subscription charge is also a separate amount. Taxes, discounts, credits, routing, and provider billing rules can make an invoice differ from the estimate.

Published rates come from a dated price snapshot. A provider offer from the model catalog may supply an estimate for a model missing from the price book. The CLI marks that fallback with ~. If no usable price is available, the tokens remain in the report without a price. Check pricing coverage before comparing monetary totals.

Confidence labels

exact, strong, and derived describe how a usage event is identified across repeated scans. They do not describe a statistical confidence interval around the token count.

See confidence and repeated scans. Unavailable readings and recovered rollups have their own limitations. They should not be treated as complete session-level measurements.

Preserve and inspect your history

Scheduled scans preserve counters before tools remove their source records. Claude Code normally deletes transcripts after 30 days. Its rollup can recover some older daily/model totals, with less detail than the original sessions.

tokenstat summary
tokenstat models
tokenstat projects
tokenstat doctor

doctor checks archive health and reconciliation. export produces CSV or JSON for your own analysis.

Data and sync

The local usage archive contains counters and metadata, including project and session identifiers. Conversation text is excluded from that archive. Optional account sync sends aggregates with hashed project keys.

Workspace features and remote connections handle other data separately. Read what tokenstat accesses and the usage-sync payload.