Cost and pricing

Cost is computed in the SDK, per call, from the token counts the provider returned and a pricing catalog bundled with the package.

Token counts are read, not estimated

Counts come from the provider's response: usage.input_tokens for Anthropic, usage.prompt_tokens for OpenAI-shaped APIs, usageMetadata.promptTokenCount for Gemini. If the provider billed 1,412 input tokens, that is the number recorded.

Optional prompt analysis produces separate estimates for structural metrics such as context-window utilisation. Those live in their own fields and are never used for cost.

Model lookup

Pricing is resolved in three steps:

1. Exact match. claude-sonnet-4-6 is in the catalog and priced directly.
2. Prefix match. claude-sonnet-4-6-20260101 is not, but it starts with a catalog entry and inherits that price. This is why dated model snapshots do not each need an entry.
3. Regional prefix stripping, for Bedrock only. apac.amazon.nova-micro-v1:0 is a cross-region inference profile, so the geography prefix is removed and the underlying model is priced.

The catalog is shared with the backend, so a price is never defined in two places with two values.

Rolling aliases

Some providers accept an alias that resolves to a concrete model, such as Gemini's gemini-flash-lite-latest. An alias cannot be priced, because what it points to changes without notice.

The SDK therefore prefers the model reported in the response over the model in the request. If you request an alias, the event records the concrete model that served it. Without this, alias requests match nothing in the catalog and fall back to a generic estimate.

Cached tokens

Anthropic prompt caching bills three token classes at three rates, and all three are recorded separately:

Cost sums input, output, cache read, and cache write, so a cached workload reports the saving rather than being billed at the standard input rate.

Streamed OpenAI calls record cache tokens as zero.

Decimal arithmetic

All cost arithmetic uses Python's Decimal. Prices are values like 0.000003 per token summed across millions of events, and binary floating point accumulates visible drift at that scale.

Unknown models

A model matching nothing in the catalog is still recorded. It is priced with a generic fallback estimate and logs a warning:

capsera: no pricing found for model 'some-new-model' — using fallback estimate

Recording an approximate cost is preferable to discarding the call, because a missing event makes totals silently wrong. If you see this warning, the model needs a catalog entry. Report it and it will be added in the next release.

Reconciling against a provider invoice

Expect two differences.

Timing. Capsera records at call time. Providers bill on their own cycle, so day boundaries will not align exactly.

Failed calls. An error is recorded as a zero-cost event with is_error=True. Providers usually do not bill for a failed request, but they do bill for one that consumed tokens before failing, such as a stream that ended mid-response.

For a larger discrepancy, run with debug=True. The per-call log line reports model, tokens, and computed cost, which narrows the disagreement to a specific model.