# Response usage

> Read normalized token usage and preserve absent versus zero metadata.

- Path: `Guides > Inference > Responses > Response usage`
- Human: https://looprig.com/docs/guides/inference/responses/usage
- Machine index: https://looprig.com/llms.txt

`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

```go
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)
```

```go
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`](https://github.com/looprig/core/blob/main/content/usage.go), [`inference/client.go`](https://github.com/looprig/inference/blob/main/client.go)
- Tests: [`core/content/usage_test.go`](https://github.com/looprig/core/blob/main/content/usage_test.go), [`inference/stream/stream_test.go`](https://github.com/looprig/inference/blob/main/stream/stream_test.go)

Related: [Terminal stream results](/docs/guides/inference/streaming/terminal-results.md), [AIMessage](/docs/guides/inference/messages/message-types/ai-message.md).