Cost Tracking & Token Usage

Token accounting works across providers — Gemini and Anthropic usage is normalized to the shared shape at decode time, so these accessors and the pricing table apply uniformly to Chat, Responses, and the agentic verb.

For a worked walkthrough — reading usage, the silent-\$0 footgun on unpriced models, custom pricing, and per-Chat cumulative totals — see the Cost Tracking guide.

Token Usage

UniLM.TokenUsage — Type

TokenUsage(; prompt_tokens=0, completion_tokens=0, total_tokens=0, cached_tokens=0, reasoning_tokens=0)

Token usage statistics returned by the API.

cached_tokens (a subset of prompt_tokens served from the prompt cache) and reasoning_tokens (a subset of completion_tokens spent on hidden reasoning) are reported by newer models via the *_tokens_details objects; they default to 0 when the provider omits those details. estimated_cost bills cached_tokens at the discounted cached-input rate.

source

UniLM.token_usage — Function

token_usage(result::LLMRequestResponse) -> TokenUsage

Extract token usage from a token-billed API result (chat, Responses, embeddings and their image counterparts); failures of those APIs report zero usage.

Results from APIs that do not report token usage at all — audio, files, batches, moderations, vector stores, video, … — throw an ArgumentError. A zero would be indistinguishable from a genuinely free call and would quietly under-count spend.

source

Cost Estimation

UniLM.estimated_cost — Function

estimated_cost(result::LLMRequestResponse; model=nothing, pricing=DEFAULT_PRICING) -> Float64

Estimate the cost in USD for a single API call result. If model is not provided, it is inferred from the result when possible.

Returns 0.0 for results that carry no billable usage (failures) or an unpriced model. Throws ArgumentError for result types outside the token-billed APIs — see token_usage; their price is not a zero this function can report.

source

UniLM.cumulative_cost — Function

cumulative_cost(chat::Chat) -> Float64

Return the cumulative estimated cost accumulated by chatrequest! calls on this Chat.

source

UniLM.DEFAULT_PRICING — Constant

Default per-token pricing; current OpenAI and Gemini rows verified on 2026-09-07 (prices drift — re-verify before relying on them). Cached input is billed at the discounted cached_input rate; reasoning tokens are already counted within output tokens. These are standard short-context text rates: cache writes, long-context surcharges, service-tier adjustments, multimodal rates, and hosted-tool fees are not included.

source