Creates a new ModelUsage instance.
Number of tokens used in the prompt/input
Number of tokens generated in the completion/output
Optionalcost: numberOptional cost of the execution
OptionalcostCurrency: stringOptional currency code for the cost (e.g., 'USD', 'EUR', 'GBP')
OptionalcacheNumber of input tokens served from the provider's prompt cache (a cache READ / hit). These are billed at a steep discount versus normal input tokens (e.g. Anthropic ~0.1x, OpenAI ~0.5x, Gemini ~0.1x) and are the primary source of prompt-caching savings.
DISJOINT from promptTokens (which is uncached/net-new only) on EVERY provider — the
adapter normalizes to guarantee this. So totalInputTokens = promptTokens + cacheReadTokens + cacheWriteTokens holds uniformly.
Optional/additive: declared optional so existing object-literal ModelUsage construction
sites keep compiling. new ModelUsage(...) instances default it to 0; treat undefined as 0.
OptionalcacheNumber of input tokens written to the provider's prompt cache (a cache WRITE / creation). Some providers charge a premium for cache writes (e.g. Anthropic ~1.25x normal input); others (OpenAI, Gemini, Groq, Cerebras, Fireworks) do not bill/report writes separately, so this stays 0. DISJOINT from promptTokens and cacheReadTokens.
OptionalcompletionOptional time in milliseconds for the model to generate the completion/response tokens. This is a provider-specific timing metric that may not be available from all providers.
Number of tokens generated by the model in its response. This represents the length of the model's output.
OptionalcostOptional cost of this execution. The currency is specified in the costCurrency field. Some providers (like Anthropic) provide this information directly in their API responses.
OptionalcostOptional ISO 4217 currency code for the cost field. Examples: 'USD', 'EUR', 'GBP', 'JPY', etc. If not specified when cost is provided, the currency is provider-specific.
OptionalinputContinuous input quantity consumed by the execution, in unitKind's base measure — e.g. seconds of audio submitted for transcription. Undefined for token-billed executions.
Left undefined rather than zeroed when a provider does not report the quantity: a zero here prices as free, which is a worse answer than "no usage recorded".
OptionaloutputContinuous output quantity produced by the execution, in unitKind's base measure — e.g. seconds of audio synthesized, or number of images generated. Undefined for token-billed executions.
OptionalpromptOptional time in milliseconds for the model to ingest and process the prompt. This is a provider-specific timing metric that may not be available from all providers.
Number of UNCACHED ("net-new") input tokens — i.e. prompt/input tokens that were NOT served from the provider's prompt cache. This is normalized to the SAME meaning across every provider (uniform across all providers): cached tokens are never counted here.
Provider adapters are responsible for normalizing into this shape:
input_tokens excluding cached tokens → use as-is.The cache buckets (cacheReadTokens, cacheWriteTokens) are DISJOINT from this. Total input the provider processed = totalInputTokens.
OptionalqueueOptional queue time in milliseconds before the model started processing the request. This is a provider-specific timing metric that may not be available from all providers.
OptionalunitThe base measure inputUnits / outputUnits are counted in. undefined means
the execution was token-billed and only the token fields are meaningful.
Total input tokens the provider processed: uncached (promptTokens) + cache reads + cache writes. This is the figure to price at the input rate (until cache-aware per-bucket pricing is added) and equals what the provider's native "prompt token" count was before normalization. Use THIS (not promptTokens) for cost so cached tokens aren't dropped.
Total UNCACHED tokens for the call: uncached input (promptTokens) + completion.
Deliberately EXCLUDES the cache buckets so the MemberJunction invariant
TokensUsed === TokensPrompt + TokensCompletion (enforced by AIPromptRun's CK_AIPromptRun_Tokens
constraint + generated validation) continues to hold once promptTokens is net-new. The full
token count INCLUDING cache is totalInputTokens + completionTokens — use totalInputTokens
for cost so cached tokens are still billed.
promptTokens + completionTokens
StaticForBuilds usage for a continuous-media execution, with the token fields zeroed.
The base measure being counted — never the billing measure
Quantity consumed on the input side
Quantity produced on the output side; defaults to 0
Represents usage and cost information for an AI model execution.
This class tracks the number of tokens used in both the prompt (input) and completion (output) phases of an AI model execution, along with optional cost information when provided by the AI provider.
For models whose unit of work is not a token — speech-to-text priced per minute of audio, image generation priced per image — the quantity lives in inputUnits / outputUnits with unitKind naming its measure. Continuous quantities are never folded into the token fields: a run that reports 90 "tokens" meaning 90 minutes corrupts every token rollup and dashboard downstream of it.
ModelUsage
Since
2.43.0