Struct Usage 

#[non_exhaustive]
pub struct Usage {
    pub input_tokens: Option<u64>,
    pub output_tokens: Option<u64>,
    pub total_tokens: Option<u64>,
    pub cached_input_tokens: Option<u64>,
    pub cache_creation_input_tokens: Option<u64>,
    pub tool_use_prompt_tokens: Option<u64>,
    pub reasoning_tokens: Option<u64>,
    pub cost: Option<Cost>,
}

The token usage a provider reported for one completion.

Every provider mapping keeps one contract, so the counters read the same way on every provider:

• cached_input_tokens + cache_creation_input_tokens <= input_tokens: input counts every prompt token, cache reads and writes included.
• reasoning_tokens <= output_tokens: output counts every generated token, reasoning included.
• total_tokens == input_tokens + output_tokens, absent unless both are reported.

A counter the provider did not send is None; a reported zero is Some(0). Serialized as the same keys, absent when None.

use rig_core::completion::Usage;

let usage = Usage::new().input_tokens(12).output_tokens(3).total_tokens(15);
assert_eq!(usage.input_tokens, Some(12));
assert!(usage.cost.is_none());

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: Option<u64>

Every input token of the request: uncached, read from a cache, written to a cache, and any prompt a provider’s hosted tools added.

output_tokens: Option<u64>

Every output token, reasoning included.

total_tokens: Option<u64>

input_tokens + output_tokens; absent unless both are reported.

cached_input_tokens: Option<u64>

The part of input_tokens read from a provider-managed cache.

cache_creation_input_tokens: Option<u64>

The part of input_tokens written to a provider-managed cache.

tool_use_prompt_tokens: Option<u64>

The part of input_tokens a provider’s hosted tools added to the prompt.

reasoning_tokens: Option<u64>

The part of output_tokens spent on internal reasoning (“thinking”, “thoughts”).

cost: Option<Cost>

What the turn cost in USD, when known. Never derived from the token counters here, and none of them is derived from it. A cost the provider reports is its figure. One priced from the built-in catalog (Pricing::cost) is the standard-tier list price of the counted tokens: it leaves out the service tier, long-context price tiers and hosted-tool fees (web search, code execution), so it can be lower than the bill.

Implementations

impl Usage

pub const fn new() -> Self

No counter and no cost reported.

pub fn is_reported(&self) -> bool

Whether the provider reported any counter or a cost.

pub fn input_tokens(self, tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, Self::input_tokens.

pub fn output_tokens(self, tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, Self::output_tokens.

pub fn total_tokens(self, tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, Self::total_tokens.

pub fn cached_input_tokens(self, tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, Self::cached_input_tokens.

pub fn cache_creation_input_tokens(self, tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, Self::cache_creation_input_tokens.

pub fn tool_use_prompt_tokens(self, tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, Self::tool_use_prompt_tokens.

pub fn reasoning_tokens(self, tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, Self::reasoning_tokens.

pub fn cost(self, cost: impl Into<Option<Cost>>) -> Self

Set, or with None clear, Self::cost.

Trait Implementations

impl Add for Usage

type Output = Usage

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self::Output

Performs the + operation.

impl AddAssign for Usage

Token counters add where an unreported side adds nothing. Cost sums only when both sides have one: a turn whose cost is unknown makes the sum unknown, rather than too low. A side that reports nothing at all (Usage::is_reported is false) is the identity, so a fold from Usage::default keeps its first turn’s cost.

fn add_assign(&mut self, other: Self)

Performs the += operation.

impl Clone for Usage

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Usage

impl Debug for Usage

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

Formats the value using the given formatter.

impl Default for Usage

fn default() -> Self

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 From<&Usage> for Usage

fn from(value: &Usage) -> Usage

Converts to this type from the input type.

impl From<Usage> for Usage

fn from(value: Usage) -> Usage

Converts to this type from the input type.

impl PartialEq for Usage

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

Equality operator ==.

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

Inequality operator !=.

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 StructuralPartialEq for Usage