Interface: LlmUsageEvent
Defined in: packages/agentos/src/api/observers.ts:44
Payload delivered to a registered usage observer once an LLM call resolves. Mirrors the agentos-side fields that downstream cost / billing systems care about.
Properties
durationMs?
optionaldurationMs:number
Defined in: packages/agentos/src/api/observers.ts:103
Wall-clock duration of the whole call in milliseconds, measured from surface entry (post-option parse, pre-routing) to the moment the observer fires. For streaming surfaces this spans the full stream — first byte through final chunk — not just time-to-first-token.
Fallback semantics: on a provider-fallback, generateText fires ONE
event (from the winning hop) whose durationMs is threaded to span the
whole call — failed primary attempts included — so a slow fallback turn
reads as slow. streamText instead fires one event per hop: the inner
hop event times that hop, and an aggregate outer event times the whole
call. Either way durationMs is never less than the time the caller
actually waited on the event that carries the final result.
Optional so hosts tolerate events from older agentos versions.
fallbackDepth?
optionalfallbackDepth:number
Defined in: packages/agentos/src/api/observers.ts:69
Set (>= 1) when this event was served by a provider-fallback leg rather than the requested primary; the value is the hop number. Absent on primary-served calls. Lets hosts tell a leg row from a primary row instead of inferring it from paired token counts — during the 2026-07-20..26 quota outage every diverted call was indistinguishable from primary traffic in cost telemetry.
finishReason?
optionalfinishReason:string
Defined in: packages/agentos/src/api/observers.ts:74
Mirrors the finishReason on the GenerateText result so observers
can distinguish a clean stop from a token-cap truncation.
model
model:
string
Defined in: packages/agentos/src/api/observers.ts:48
Resolved model id (e.g. 'gpt-4o', 'claude-sonnet-4-6').
provider
provider:
string
Defined in: packages/agentos/src/api/observers.ts:46
Resolved provider id (e.g. 'openai', 'anthropic', 'openrouter').
servingProvider?
optionalservingProvider:string
Defined in: packages/agentos/src/api/observers.ts:119
Upstream host that actually served the call when the provider is an
aggregator (OpenRouter: Groq, DeepInfra, ...). Mirrors the
servingProvider response telemetry; absent for direct providers
and surfaces that don't track it.
source?
optionalsource:string
Defined in: packages/agentos/src/api/observers.ts:60
Opt-in source label set by the caller via the source option
(e.g. 'narrator_turn', 'companion_reply', 'world_compile_job').
Hosts use this to tag emitted rows with their own meter_key.
surface
surface:
"generateImage"|"generateText"|"generateObject"|"streamText"|"streamObject"|"embedText"
Defined in: packages/agentos/src/api/observers.ts:80
Which agentos surface fired the event. Lets a single observer route generateText, generateObject, generateImage, embedText, etc. into different meters when needed.
ttfbMs?
optionalttfbMs:number
Defined in: packages/agentos/src/api/observers.ts:112
Time-to-first-part for streaming surfaces, in milliseconds: surface
entry to the first StreamPart yielded to the consumer (text or
tool-call alike). Undefined on non-streaming surfaces and when the
stream errored before producing any part. The latency triage
counterpart to durationMs — a high ttfb with a short remainder
points at routing/prefill; the inverse points at generation length.
usage
usage:
TokenUsage
Defined in: packages/agentos/src/api/observers.ts:54
Aggregated token usage for the call — promptTokens, completionTokens,
totalTokens, costUSD, cacheReadTokens, cacheCreationTokens.
Mirrors the usage field on the GenerateText/Object result.