A cost record is the token and money cost of one attempt, summed over every model API request the attempt made.
Token and money cost of one attempt, summed over all API requests the attempt made. Cached input is separated from uncached because the two are priced differently and blur cost comparisons when merged; cache creation is split by retention bucket for the same reason.
​
integer
Uncached input tokens.
​
integer
Input tokens served from cache (cache reads).
​
integer
Input tokens written to cache, all retention buckets together, when the provider bills them separately. When the two bucket fields are also present their sum must equal this.
​
integer
Cache-creation tokens in the 5-minute retention bucket.
​
integer
Cache-creation tokens in the 1-hour retention bucket, priced higher than the 5-minute bucket.
​
integer
​
integer
Reasoning tokens, as a breakdown of output_tokens: output_tokens includes them, as OpenAI and Anthropic report them. A producer whose source reports reasoning separately adds it into output_tokens.
​
integer
Number of model API requests aggregated into this record.
​
number
Billed cost in US dollars when the producer knows it. Consumers should prefer recomputing from tokens and a dated price table.
​
string
How the counts were attributed to this attempt. measured: summed from usage records that identify this attempt exactly (a per-session or per-agent transcript, or per-request usage tied to the attempt). allocated: apportioned from a coarser aggregate (per-day or per-worktree usage) by a heuristic such as a time-window join; consumers should down-weight accordingly. Absent means unknown. Required, and required to be measured, when the producer is the extractor (rule E171); from v0.3 a document whose producer is loopmath may give allocated when cost.ext[dev.loopmath.logmatch] marks a heuristic log match or a shared session.Recommended values (open set): measured, allocated.
​
Ext
​
Tariff

​
Streams

Tokens are kept per stream because the streams are priced differently. Cached input costs an order of magnitude less than uncached input, and merging the two blurs every cost comparison. Cache creation is kept apart for the same reason, and split by retention bucket where the provider bills the buckets differently.
  • When cache_creation_tokens, cache_creation_5m_tokens and cache_creation_1h_tokens are all present, the two buckets MUST add up to the total (E170).
  • input_tokens is uncached input only. Many tools count cache reads inside input; their exporters subtract cached_input_tokens first. See Implementations.
  • output_tokens includes reasoning tokens, as OpenAI and Anthropic report them, and reasoning_tokens is a breakdown of it. A producer whose source reports reasoning separately from output adds it into output_tokens. Never add reasoning_tokens to output_tokens when totalling a cost.
  • An absent cost record means the cost is unknown, not zero.

​
Basis

Per-attempt cost is the producer’s job, and many tools do not record usage per attempt. basis says how the counts were attributed:
  • A consumer SHOULD weigh allocated costs less than measured ones.
  • A producer MUST NOT write measured for counts it apportioned.
  • When the producer is loopmath’s log extractor, every cost is measured (E171). From 0.3 there is one exception: allocated is allowed when cost.ext["dev.loopmath.logmatch"] marks a heuristic log match or a shared session.

​
Dollars and tariffs

usd is optional. A consumer SHOULD prefer recomputing dollars from tokens and a dated price table over trusting usd, because prices change and tools price differently. When a producer writes usd, it SHOULD also write the tariff it used. The price table used to compute usd.
​
string
Price table version: the prices.toml sha256 prefix.At most 200 characters.
​
string
The tariff date used, YYYY-MM-DD.At most 40 characters.
​
string
Where the prices came from.At most 500 characters.
​
Ext

Privacy