Struct Usage 

pub struct Usage {
    pub uncached_input_tokens: u32,
    pub cache_read_tokens: u32,
    pub cache_write_tokens: u32,
    pub completion_tokens: u32,
    pub cost: Option<f64>,
    pub upstream_inference_cost: Option<f64>,
    pub reasoning_tokens: Option<u32>,
}

Normalized token usage + cost, the common currency every provider’s Provider parses its native wire shape into.

Input tokens are split into THREE DISJOINT, ADDITIVE buckets so caching is priced correctly across every provider’s differing wire conventions:

• uncached_input_tokens: full-price prompt tokens (no cache involved),
• cache_read_tokens: served from a warm cache (cheap, ~0.1× input),
• cache_write_tokens: written to the cache this request (a premium, ~1.25×).

They never overlap, so total input = the sum of the three, and cost is a clean weighted sum with no subtraction (the old single cached_tokens field forced a subtract that was correct for OpenAI’s “cached is a subset of prompt_tokens” wire but WRONG for Anthropic’s “input_tokens already excludes cached” wire). Each provider’s parser maps its native fields into these disjoint buckets.

Built by the provider (the nested per-provider wire shapes don’t match these flat fields), and serialized into node metadata for diagnostics. Deliberately NOT Deserialize: a derived flat-field deserializer would silently produce all-zero/None fields against the real nested payloads.

Fields

uncached_input_tokens: u32

Full-price input tokens (NOT read from nor written to cache this request).

cache_read_tokens: u32

Input tokens served from a warm cache (priced at the cache-read rate).

cache_write_tokens: u32

Input tokens written to the cache this request (priced at the cache-write premium). Non-zero only on the request that creates/refreshes a cache entry.

completion_tokens: u32

Number of tokens in the completion (output).

cost: Option<f64>

Cost in USD (for OpenRouter, the fee; may be 0 on a BYOK free tier or when the provider returns no native cost). None if the wire carried no cost.

upstream_inference_cost: Option<f64>

Upstream inference cost (only for BYOK requests, the actual cost charged by the provider like Google Vertex or Bedrock)

reasoning_tokens: Option<u32>

Reasoning tokens (for models that support it)

Implementations

impl Usage

pub fn prompt_tokens(&self) -> u32

Total input tokens processed = the three disjoint input buckets summed.

pub fn total_tokens(&self) -> u32

Total tokens (input + output).

Trait Implementations

impl Clone for Usage

fn clone(&self) -> Usage

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Usage

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

Formats the value using the given formatter.

impl Default for Usage

fn default() -> Usage

Returns the “default value” for a type.

impl Serialize for Usage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.