What tokenstat counts, and where the numbers come from

tokenstat does not sit between you and a model. It never proxies a request, never holds an API key, and never asks a vendor for your usage. It reads what your coding tools have already written to disk, adds it up, and shows you the total.

That design decides everything else about it, including the parts that are approximate. This guide explains what is actually being counted.

The four numbers behind every total

Every request against a model produces four separate token counts, and collapsing them into one figure is the most common way usage stats mislead:

• Fresh input: text the model had not seen before, billed at the full input rate.
• Cache write: input stored so the next request can skip re-reading it. Costs more than fresh input, once.
• Cache read: input served from that cache. Usually about a tenth the price of fresh input.
• Output: what the model wrote. Several times the input rate, and almost always the smallest of the four by volume.

On a normal agent workload cache reads are the overwhelming majority of tokens and a minority of the cost. A profile that says "7 billion tokens" is mostly saying "the same context was re-read a great many times", which is why tokenstat shows the split rather than the headline.

Where each tool's numbers come from

Nothing here involves a network call. If a tool stores nothing locally, tokenstat cannot see it, and it says so rather than estimating.

Confidence, and why it is shown

Not every tool reports token counts, so not every number is a measurement. tokenstat keeps that distinction instead of flattening it:

• exact: the tool wrote the token count down and we read it.
• strong: reconstructed from what the tool did record, with high confidence.
• derived: inferred from local files, and the loosest of the three.

You will see this split on the report output and on a public profile. A derived number is still useful. It just should not pass itself off as a measurement, so it does not.

Cost is modelled, not billed

tokenstat has no access to your invoice. What it shows is the four token counts priced at each model's published rate.

For subscription usage that is the only figure that can exist, and it is the interesting one: it tells you what the same work would have cost per token, which is how you find out whether a plan is worth keeping. For pay-per-token usage it is an estimate, close but not an invoice.

Where a model's id cannot be matched to a published rate, its tokens are counted and excluded from the cost rather than guessed at. That is why a profile reports the share of tokens it was able to price.

What leaves your machine

Nothing, unless you run tokenstat login and tokenstat sync.

If you do, what is sent is counters: a date, a tool id, a model id, four token counts, a request count, and an opaque hash standing in for a project. Never a prompt, a file path, a project name, or a session id. The project hash is an HMAC computed on your machine with a salt that stays there, so it can be counted but never read back.

The local archive is yours either way, and tokenstat export gives you all of it in a format nothing else needs to interpret.

Next

• tokenstat report for the local view, which is always the complete one.
• tokenstat doctor if a tool you use is not showing up, which usually means its local store moved.