Usage Normalization

Last updated 2026-10-02

How vendor-specific token counters fold into one Usage shape.

The Usage shape

Vendors name token fields differently: the OpenAI family uses prompt_tokens / completion_tokens, Anthropic uses input_tokens / output_tokens, and cache fields diverge further. Usage.UnmarshalJSON folds them into one shape:

type Usage struct {
    Input       int
    Output      int
    CacheCreate int
    CacheRead   int
}

Cache accounting

prompt_tokens_details.cached_tokens is subtracted from Input and folded into CacheRead, so a cache hit is never counted twice.

Related

• Balance and Quota: account-level remaining credit
• Message Types: where Usage sits in Output