Skip to main content

Interface: TokenUsage

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

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

Properties​

cacheCreationTokens?​

optional cacheCreationTokens: number

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

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:175

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:148

Number of tokens in the model's response.

costUSD?​

optional costUSD: number

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

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

inclusiveInputTokens?​

optional inclusiveInputTokens: number

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

Provider-independent total input tokens INCLUDING cached reads/writes, summed across steps (spec batch-1 C1). Anthropic reports input exclusive of cache (this field adds it back); OpenAI/OpenRouter report prompt tokens already inclusive (used as-is). 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:146

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

totalTokens​

totalTokens: number

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

Sum of promptTokens and completionTokens.