Skip to content
LLM Usage Metrics

Pricing

llm-usage-metrics uses LiteLLM pricing data to estimate costs when events do not include explicit cost. For the design behind these knobs — the fallback ladder, model-name matching, and the cost engine — see the Pricing Pipeline deep dive.

Pricing source

Section titled “Pricing source”
  • primary source: LiteLLM pricing JSON
  • cache: online runs use a fresh cache first, then refresh from LiteLLM when needed
  • fallback: stale cache is used when live refresh fails
  • bundled snapshot: the default LiteLLM pricing URL can fall back to a bundled snapshot
  • offline mode: --pricing-offline skips network and uses cache, stale cache, or the bundled snapshot
Terminal window
llm-usage monthly --pricing-offline

When the bundled snapshot is used, stderr includes a warning with the snapshot date:

Pricing: using the bundled LiteLLM snapshot from 2026-07-08 (run online to refresh).

Run without --pricing-offline to refresh the cache from LiteLLM. Custom --pricing-url values do not fall back to the bundled default snapshot; they must load from their matching cache or network URL.

When pricing.offline: true is set in the config file, there is no --no-pricing-offline flag; force a one-off online refresh by bypassing the config for that run (LLM_USAGE_CONFIG_PATH=/nonexistent llm-usage monthly) or edit the config.

For cache lifecycle and tuning knobs, see Caching.

Cost modes

Section titled “Cost modes”

Each event is either:

  • explicit: source included a valid cost
  • estimated: cost derived from pricing data

Explicit costUsd: 0 events are re-priced from LiteLLM when model pricing exists.

Row cost rendering

Section titled “Row cost rendering”
  • - when all contributing events are unresolved
  • ~$... when only part of the row cost is known
  • $... when row cost is fully resolved

Override pricing URL

Section titled “Override pricing URL”
Terminal window
llm-usage monthly --pricing-url https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json

Per-model pricing overrides

Section titled “Per-model pricing overrides”

A JSON file of per-model rates takes precedence over LiteLLM pricing. Use it for internal/custom models, negotiated rates, or values you want to correct.

Terminal window
llm-usage monthly --pricing-overrides ./pricing-overrides.json

File shape:

{
  "models": {
    "my-internal-model": { "inputPer1MUsd": 1, "outputPer1MUsd": 2 },
    "claude-opus-4-8": {
      "inputPer1MUsd": 12,
      "outputPer1MUsd": 60,
      "cacheReadPer1MUsd": 1.2,
      "cacheWritePer1MUsd": 18.75
    }
  }
}

Only inputPer1MUsd and outputPer1MUsd are required; cacheReadPer1MUsd, cacheWritePer1MUsd, reasoningPer1MUsd, and reasoningBilling (included-in-output or separate) are optional. Rates must be finite, non-negative numbers. Invalid required rates discard the entry, while invalid optional rates are ignored. Model names match case-insensitively.