Struct Usage 

#[non_exhaustive]
pub struct Usage {

    pub input_tokens: Option<u64>,
    pub output_tokens: Option<u64>,
    pub cache_read_tokens: Option<u64>,
    pub cache_write_tokens: Option<u64>,
    pub context_tokens: Option<u64>,
    pub context_window: Option<u64>,
    pub max_output_tokens: Option<u64>,
    pub reasoning_tokens: Option<u64>,
    pub cost_usd: Option<f64>,
    pub premium_requests: Option<u64>,
    pub ai_credits_nano: Option<u64>,
    pub duration_ms: Option<u64>,
    pub api_duration_ms: Option<u64>,
}

Token and cost accounting for a run.

Every field is optional because the three agents report different subsets: Claude reports full token counts and a dollar cost, Codex reports tokens, Copilot reports premium requests and no tokens at all. An absent field means “this agent did not say”, never zero.

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>

Input tokens that were not served from cache.

Normalized, because the vendors disagree on what “input” counts. Claude reports the uncached remainder and Codex reports the whole prompt with the cached part included, so this field is derived on the Codex side by subtracting. Reading it as the same quantity on both was the point.

output_tokens: Option<u64>

Generated tokens.

cache_read_tokens: Option<u64>

Input tokens served from the prompt cache.

cache_write_tokens: Option<u64>

Input tokens written into the prompt cache.

context_tokens: Option<u64>

Every input token the turn was charged for, cached or not.

The size of the conversation as the model saw it, which makes this the context tracker: compare it to Usage::context_window. It is already a running total, since the cached portion is the prior conversation, so summing it across turns double counts. See Usage::accumulate.

context_window: Option<u64>

The selected model’s context window, where the agent reports one.

Claude alone does. Without it a host can still show tokens used, just not a share of the limit.

max_output_tokens: Option<u64>

The most tokens the model may generate in one reply.

reasoning_tokens: Option<u64>

Output tokens spent on reasoning rather than the visible answer, where the agent separates them. Codex alone does.

cost_usd: Option<f64>

Cost in USD, when the agent priced the run itself. Never inferred from a local price table, because a guessed cost is worse than no cost.

premium_requests: Option<u64>

Copilot’s premium-request count, its legacy billing unit.

ai_credits_nano: Option<u64>

Copilot’s AI-credit spend for the session, in nano units, which is the unit that replaced premium requests. Divide by 1e9 for credits.

Session-scoped and cumulative within a session, verified by running Copilot repeatedly: it restarts each run rather than accruing across them. Not an account balance.

duration_ms: Option<u64>

Wall-clock time the run took, in milliseconds.

api_duration_ms: Option<u64>

Time spent waiting on the provider, in milliseconds.

Implementations

impl Usage

pub fn is_empty(&self) -> bool

Whether the agent reported anything at all.

pub fn accumulate(&mut self, turn: &Usage)

Fold one turn’s usage into a session running total.

Provided because the obvious loop is wrong. Cost and generated tokens accumulate, but the context-shaped figures are already cumulative: an agent re-sends the whole conversation each turn and reports it, mostly as cache reads. Summing those across turns counts the same conversation once per turn, and the error grows with the session.

So additive fields add, and context-shaped fields take the newer value:

field	behaviour
output_tokens, reasoning_tokens, input_tokens	summed
cost_usd, premium_requests, duration_ms, api_duration_ms	summed
context_tokens, cache_read_tokens, cache_write_tokens	latest
context_window, max_output_tokens	latest
ai_credits_nano	latest, being a session total already

input_tokens sums because it is the uncached remainder, which is new work each turn.

pub fn context_used(&self) -> Option<f64>

Share of the context window in use, from 0.0 to 1.0.

None unless the agent reported both the tokens and the window, which today means Claude. Returns the ratio rather than a formatted string or a bar, so a host renders it however it likes.

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 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() -> 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

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