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.
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.
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
Represents token 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.
ModelUsage
Since
2.43.0