Response.Usage is an optional pointer to core/content.Usage. It normalizes provider-specific counters and keeps absent usage distinct from a present zero value.

API surface

type Usage struct {
	InputTokens         TokenCount
	OutputTokens        TokenCount
	CacheReadTokens     TokenCount
	CacheCreationTokens TokenCount
	ReasoningTokens     TokenCount
}

func (u Usage) Validate() error
func (u Usage) ContextTokens() (TokenCount, error)
func (u Usage) TotalTokens() (TokenCount, error)
func (u Usage) Add(other Usage) (Usage, error)

if response.Usage != nil {
	contextTokens, err := response.Usage.ContextTokens()
	if err != nil {
		return err
	}
	total, err := response.Usage.TotalTokens()
	if err != nil {
		return err
	}
	fmt.Println(contextTokens, total)
}

ReasoningTokens cannot exceed OutputTokens. Derived additions return typed *UsageOverflowError on overflow. Codec and stream paths validate usage before authorizing it as terminal metadata.

Message-level usage

AIMessage.Usage is the same normalized shape at message scope. The top-level response field is the preferred response accounting value; do not assume both pointers are present or identical when adapting a provider.

Proof

Source: core/content/usage.go, inference/client.go
Tests: core/content/usage_test.go, inference/stream/stream_test.go