Struct Usage 

#[non_exhaustive]
pub struct Usage {
    pub input_tokens: u32,
    pub output_tokens: u32,
    pub cached_input_tokens: u32,
    pub cache_creation_input_tokens: u32,
    pub reasoning_tokens: u32,
    pub safety_ratings: Vec<SafetyRating>,
}

Per-call accounting from the vendor.

Token fields are u32 with default 0 — every shipping codec populates them, and 0 is the natural “no cache hit” / “no reasoning” value. Whether the field is meaningful for the (codec, model) pair is governed by Capabilities flags, not by an option/null distinction here.

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.

input_tokens: u32

Tokens consumed from the prompt this call.

output_tokens: u32

Tokens produced as output (assistant content).

cached_input_tokens: u32

Tokens served from the prompt cache (typically discounted).

cache_creation_input_tokens: u32

Tokens written to the prompt cache (typically billed at a premium).

reasoning_tokens: u32

Tokens spent on internal reasoning (Anthropic thinking, OpenAI o-series reasoning, Gemini thinking budget).

safety_ratings: Vec<SafetyRating>

Per-category safety scores reported by the vendor (Gemini today; empty otherwise).

Implementations

impl Usage

pub fn new(input_tokens: u32, output_tokens: u32) -> Self

Construct a Usage from the two universally-populated token counts; cache, reasoning, and safety fields stay at their defaults (0 / Vec::new()). Use the with_* setters to override the rest.

pub const fn with_cached_input_tokens(self, tokens: u32) -> Self

Override cached_input_tokens (prompt-cache reads).

pub const fn with_cache_creation_input_tokens(self, tokens: u32) -> Self

Override cache_creation_input_tokens (prompt-cache writes).

pub const fn with_reasoning_tokens(self, tokens: u32) -> Self

Override reasoning_tokens (Anthropic thinking, OpenAI o-series reasoning, Gemini thinking budget).

pub fn with_safety_ratings(self, ratings: Vec<SafetyRating>) -> Self

Attach the vendor-reported per-category safety ratings.

pub const fn billable_input(&self) -> u32

Billable input tokens — fresh prompt input plus cache writes (which vendors typically charge at a premium). Cache reads are excluded because vendors discount them, often heavily.

pub const fn total(&self) -> u32

Sum of input + output tokens (rough cost proxy when no per-bucket pricing is configured).

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<'de> Deserialize<'de> for Usage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Usage

fn eq(&self, other: &Usage) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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.

impl Eq for Usage

impl StructuralPartialEq for Usage