# `Omni.Usage`
[🔗](https://github.com/aaronrussell/omni/blob/v1.2.1/lib/omni/usage.ex#L1)

Token counts and computed costs for a generation request.

Costs are computed from token counts and the pricing data on the `%Model{}`
struct. Available on every `%Response{}` via `response.usage`.

## Struct fields

  * `:input_tokens`, `:output_tokens` — request and generated token counts
  * `:cache_read_tokens`, `:cache_write_tokens` — prompt caching token counts
  * `:total_tokens` — sum of all token counts
  * `:input_cost`, `:output_cost`, `:cache_read_cost`, `:cache_write_cost` —
    per-category USD costs derived from model pricing
  * `:total_cost` — sum of all USD cost fields

All fields default to `0`. Use `add/2` and `sum/1` to accumulate across
multiple requests.

# `t`

```elixir
@type t() :: %Omni.Usage{
  cache_read_cost: number(),
  cache_read_tokens: non_neg_integer(),
  cache_write_cost: number(),
  cache_write_tokens: non_neg_integer(),
  input_cost: number(),
  input_tokens: non_neg_integer(),
  output_cost: number(),
  output_tokens: non_neg_integer(),
  total_cost: number(),
  total_tokens: non_neg_integer()
}
```

Token usage and cost breakdown.

# `add`

```elixir
@spec add(t(), t()) :: t()
```

Sums corresponding fields of two usage structs.

# `new`

```elixir
@spec new(Enumerable.t()) :: t()
```

Creates a new usage struct from a keyword list or map.

# `sum`

```elixir
@spec sum([t()]) :: t()
```

Reduces a list of usage structs into a single summed usage.

---

*Consult [api-reference.md](api-reference.md) for complete listing*