Skip to content
pigo

Concepts · ai

Usage

Token usage tracking and cost calculation

Read this when
  • Tracking token consumption or costs
  • Working with model pricing

This page gives the token usage and cost model for provider responses. Usage tracks token consumption and cost for model responses.

Token categories

There are four categories: Input, Output, CacheRead, and CacheWrite. Total stores the aggregate. Cache categories are provider-specific. Not all providers report them.

CacheRead and CacheWrite populate automatically on supported providers because Prompt Caching is on by default. Callers who want byte-exact control over requests can disable it with ai.WithCacheRetention(ai.CacheRetentionNone).

Cost calculation

CalculateCost(model, usage) computes cost as tokens × model.Cost.{category} / 1,000,000 for each category. All costs are in USD.

Where usage appears

  • Assistant messages carry Usage with token counts from that response.
  • Agent events — agent_end carries accumulated Usage across all turns.
  • Object generation — ObjectResult includes Usage.
  • Models — Cost defines per-million-token pricing
  • Messages — assistant messages carry Usage
  • Agent State — agent-level usage tracking
  • Prompt Caching — how CacheRead / CacheWrite are produced