Struct LlmCompletionMetadata 

#[non_exhaustive]
pub struct LlmCompletionMetadata {
    pub total_tokens: Option<u32>,
    pub prompt_tokens: Option<u32>,
    pub completion_tokens: Option<u32>,
    pub cache_read_tokens: Option<u32>,
    pub cache_creation_tokens: Option<u32>,
    pub provider_cost_usd: Option<f64>,
    pub model: Option<String>,
    pub finish_reason: Option<String>,
    pub retry_metadata: Option<RetryMetadata>,
    pub response_id: Option<String>,
    pub phase: Option<String>,
    pub cache_diagnostics: Option<Value>,
}

Metadata about LLM completion

Contains token usage and completion information from the LLM response.

Token buckets are disjoint by convention (see the TokenUsage event): drivers normalize provider wire formats at the boundary so prompt_tokens carries only non-cached input, with cache_read_tokens / cache_creation_tokens additive on top. Inclusive providers (OpenAI Responses / Chat Completions, Gemini) subtract their cached count from the reported prompt total via disjoint_prompt_tokens; Anthropic / Bedrock already report disjoint buckets and pass values through unchanged.

#[non_exhaustive]: usage and cost dimensions keep being added, so construct with LlmCompletionMetadata::default and assign fields.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

total_tokens: Option<u32>

Total tokens used (non-cached prompt + cache read/creation + completion)

prompt_tokens: Option<u32>

Non-cached prompt tokens (cached reads are excluded; see struct docs)

completion_tokens: Option<u32>

Completion tokens

cache_read_tokens: Option<u32>

Tokens read from cache (reduces cost), disjoint from prompt_tokens

cache_creation_tokens: Option<u32>

Tokens written to cache (Anthropic-specific), disjoint from prompt_tokens

provider_cost_usd: Option<f64>

Authoritative cost of this generation in USD, when the provider reports it inline (e.g. OpenRouter’s usage.cost). None for providers that do not return a cost.

model: Option<String>

Model used

finish_reason: Option<String>

Finish reason

retry_metadata: Option<RetryMetadata>

Retry metadata (present if rate limit retries occurred)

response_id: Option<String>

Provider’s response ID (e.g., OpenAI response ID from response.completed). Used for previous_response_id chaining and OTel tracing.

phase: Option<String>

Execution phase from the provider’s response (e.g., “commentary”, “final_answer”). When present, this value should be preserved on the assistant message and sent back as-is in subsequent requests. Only set by providers with native phase support.

cache_diagnostics: Option<Value>

Provider-reported prompt-cache diagnostics, verbatim.

Present only when the request opted in via LlmCallConfig::cache_diagnostics and the provider answered with a diagnostics payload (today: Anthropic’s cache-diagnosis beta). The shape is provider-owned, so the runtime carries it without interpreting it.

Trait Implementations

impl Clone for LlmCompletionMetadata

fn clone(&self) -> LlmCompletionMetadata

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LlmCompletionMetadata

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for LlmCompletionMetadata

fn default() -> LlmCompletionMetadata

Returns the “default value” for a type.