Skip to main content
Every time a request passes through the Tokonomics proxy, Tokonomics parses the provider’s response, extracts token usage, and calculates the exact dollar cost using up-to-date pricing for that model. The result is a permanent, queryable record of your AI spend — no estimations, no rounding, no surprises on your provider bill.

​
What gets measured

Tokonomics captures the following metrics for every LLM call:
FieldDescription
input_tokensTokens in the prompt sent to the model
output_tokensTokens in the completion returned by the model
cache_read_tokensTokens served from the provider’s prompt cache (lower cost)
cache_creation_tokensTokens written to the provider’s prompt cache
cost_usdTotal cost in USD, calculated with 8-decimal precision
latency_msRound-trip latency to the upstream provider in milliseconds
Cache token fields are populated only when the provider reports them (for example, Anthropic prompt caching or OpenAI cached input tokens). When the provider does not report cache activity, both fields are 0.

​
Usage events

Each proxied call produces a UsageEvent — a structured record stored in your account and available via the API. Every UsageEvent contains:
  • id — UUID uniquely identifying this event
  • model — the model name as reported by the provider (e.g. gpt-4o, claude-3-5-sonnet-20241022)
  • provider — the provider slug (e.g. openai, anthropic)
  • input_tokens — prompt token count
  • output_tokens — completion token count
  • cache_read_tokens — cache read token count
  • cache_creation_tokens — cache creation token count
  • cost_usd — calculated cost in USD
  • latency_ms — upstream latency in milliseconds
  • tags — key-value pairs attached via metering headers
  • created_at — ISO 8601 timestamp of when the event was recorded
UsageEvents are immutable once written. You can retrieve them individually or in bulk via the raw events API.

​
Spend analytics

Tokonomics aggregates your UsageEvents into three levels of reporting so you always have the right level of detail:

Monthly summary

Total spend for the current billing month and what percentage of your configured budget has been used.

Daily trends

Day-by-day spend for up to the past 90 days, useful for spotting cost spikes and correlating spend with deployments.

Per-tag breakdowns

Spend grouped by any tag key you attach — for example, total cost per team, per feature, or per tenant.
All three views are available through the dashboard and via the Analytics Summary API.
Pro plan accounts retain raw UsageEvents for 90 days. Free plan accounts retain raw events for 30 days. Aggregated monthly summaries are available on both plans without a retention limit.
To pull raw events programmatically — for example to pipe them into your own data warehouse — use the Analytics Events API.