Usage Reporting Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• src/usage.rs
• src/oauth_usage.rs
• src/oauth_usage/tests.rs
• src/server.rs
• ARCHITECTURE.md

Introduction

Usage Reporting Endpoints in shunt facilitate the tracking and reporting of token consumption and resource utilization across various LLM providers. These endpoints ensure that the gateway remains compatible with the Claude Code protocol while providing transparency into how underlying models (OpenAI, Anthropic, xAI, etc.) are being utilized.

The system primary handles two types of usage data: standard Anthropic-style usage metadata returned in message responses and specific OAuth-based usage tracking for providers like ChatGPT/Codex. This data is critical for monitoring quotas, managing multi-account pools, and ensuring accurate billing or limit enforcement.
Sources: ARCHITECTURE.md:11-14, src/usage.rs

Core Usage Components

The usage reporting system is built around several key data structures that capture token counts and request metadata.

Token Counting Structures

The primary structure for tracking consumption is the Usage struct, which mirrors the Anthropic Messages API format. This allows shunt to provide seamless passthrough or translated usage statistics to Claude Code.

Field	Type	Description
input_tokens	u32	Number of tokens in the request prompt.
output_tokens	u32	Number of tokens generated in the response.
cache_creation_input_tokens	Option<u32>	Tokens used to create a new cache entry.
cache_read_input_tokens	Option<u32>	Tokens read from an existing cache entry.

Sources: src/usage.rs:5-15

OAuth Usage Tracking

For providers utilizing OAuth-based authentication (such as Codex), shunt implements specialized usage reporting logic found in src/oauth_usage.rs. This allows the gateway to track usage tied to specific OAuth sessions or organization IDs.

This diagram illustrates how usage data is collected from different provider streams before being unified for the client and internal metrics.
Sources: src/oauth_usage.rs, src/server.rs:35-40, ARCHITECTURE.md:45-50

Endpoint Integration

Usage reporting is integrated into the main inference pipeline. While there are not always standalone "usage" GET endpoints, the usage data is reported via the following mechanisms:

Response Metadata

The standard POST /v1/messages endpoint includes usage information in the final JSON block of a non-streaming response or as a message_delta event in a streaming response.

Internal Metrics Tracking

The gateway tracks usage internally to support load balancing and account rotation. The AppState maintains snapshots of usage across the account pool.

Component	Responsibility
proxy.rs	Dispatches requests and captures usage metrics upon completion.
metrics.rs	Aggregates token counts for OTel export or Prometheus scraping.
accounts.rs	Uses usage data to rotate accounts that have hit rate limits.

Sources: src/server.rs, ARCHITECTURE.md:65-75, src/usage.rs

OAuth Usage Logic

The oauth_usage module specifically handles the complexities of tracking tokens when using shared or rotated OAuth credentials.

Sequence diagram showing the flow of usage data processing for OAuth-based providers.
Sources: src/oauth_usage.rs, src/oauth_usage/tests.rs

Usage Processing Flow

1. Extraction: The gateway parses provider-specific headers or JSON fields (e.g., x-upsert-usage).
2. Translation: Provider-specific token counts are mapped to the Usage struct fields.
3. Aggregation: If a request is retried across multiple providers, usage may be aggregated depending on configuration.
4. Enforcement: If inbound_auth is enabled, usage may be checked against local user quotas.

Sources: src/oauth_usage.rs, ARCHITECTURE.md:95-100

Conclusion

Usage reporting is a foundational element of the shunt architecture, enabling it to act as a transparent yet measurable gateway. By normalizing usage data from disparate providers into a standard format, it ensures that Claude Code can accurately report token consumption while allowing operators to monitor the health and costs of their LLM infrastructure.
Sources: ARCHITECTURE.md, src/usage.rs