Skip to main content

Interface: TokenUsage

Defined in: packages/agentos/src/api/generateText.ts:196

Token consumption figures reported by the provider for a single completion call. All values are approximate and provider-dependent.

Properties​

cacheCreationExtendedTokens?​

optional cacheCreationExtendedTokens: number

Defined in: packages/agentos/src/api/generateText.ts:253

Of TokenUsage.cacheCreationTokens, the tokens written with the provider's longer cache lifetime, billed at its higher write rate: Anthropic's 1-hour writes at 2x input (usage.cache_creation.ephemeral_1h_input_tokens), OpenAI's 12-hour writes at 2.5x (cache_write_tokens_details.ttl_12h_tokens). The rest were written with the default lifetime (5 minutes on Anthropic, 30 on OpenAI, 1.25x input each). Absent when no step's provider split its writes by lifetime.


cacheCreationTokens?​

optional cacheCreationTokens: number

Defined in: packages/agentos/src/api/generateText.ts:242

Tokens written to the provider's prompt-prefix cache as a new cache entry, billed at the cache-write rate (Anthropic: 1.25× input for the 5-minute TTL, 2× for 1-hour; OpenAI GPT-5.6+: 1.25×, reported as cache_write_tokens in the usage details). Same disjointness caveat as cacheReadTokens: excluded from Anthropic's promptTokens, included in OpenAI's. A cacheReadTokens of 0 with cacheCreationTokens > 0 indicates the call that filled the cache; later cache hits flip the numbers.


cacheReadTokens?​

optional cacheReadTokens: number

Defined in: packages/agentos/src/api/generateText.ts:231

Tokens served from the provider's prompt-prefix cache, billed at the cache-read rate. Reported by Anthropic (cache_read_input_tokens), OpenAI (prompt_tokens_details.cached_tokens on Chat Completions, input_tokens_details.cached_tokens on Responses), and OpenRouter (prompt_tokens_details.cached_tokens) — all normalized into this field.

ACCOUNTING WARNING — the counters are distinct but NOT universally disjoint: Anthropic's promptTokens EXCLUDES cached tokens (its total input = promptTokens + cacheReadTokens + cacheCreationTokens), while OpenAI's promptTokens already INCLUDES cached reads (adding them double-counts). For a provider-independent input total, use the normalized inclusive input accounting rather than summing these fields.


completionTokens​

completionTokens: number

Defined in: packages/agentos/src/api/generateText.ts:200

Number of tokens in the model's response.


completionTokensEstimated?​

optional completionTokensEstimated: true

Defined in: packages/agentos/src/api/generateText.ts:260

True when some step's TokenUsage.completionTokens is an estimate rather than the provider's count: a stream the caller aborted before the provider sent its output count (Anthropic sends it only on the final message_delta) reports the characters it had streamed, at four characters a token. Absent when every count is the provider's own.


costUSD?​

optional costUSD: number

Defined in: packages/agentos/src/api/generateText.ts:204

Total cost reported by the provider across all steps, when available.


inclusiveInputTokens?​

optional inclusiveInputTokens: number

Defined in: packages/agentos/src/api/generateText.ts:216

Provider-independent total input tokens INCLUDING cached reads/writes, summed across steps, and across attempts in generateObject (spec batch-1 C1). Anthropic's promptTokens is input_tokens alone, which leaves the cache out, so this field is input_tokens + cache_creation_input_tokens + cache_read_input_tokens; OpenAI and OpenRouter report prompt tokens already inclusive (used as-is). Price input from this field: on a cached Anthropic call promptTokens counts only the uncached tail. Tri-state: undefined = no step reported enough to compute; a reported 0 is preserved.


promptTokens​

promptTokens: number

Defined in: packages/agentos/src/api/generateText.ts:198

Number of tokens in the prompt / input sent to the model.


totalTokens​

totalTokens: number

Defined in: packages/agentos/src/api/generateText.ts:202

Sum of promptTokens and completionTokens.