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?
optionalcacheCreationExtendedTokens: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?
optionalcacheCreationTokens: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?
optionalcacheReadTokens: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?
optionalcompletionTokensEstimated: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?
optionalcostUSD:number
Defined in: packages/agentos/src/api/generateText.ts:204
Total cost reported by the provider across all steps, when available.
inclusiveInputTokens?
optionalinclusiveInputTokens: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.