Skip to main content
The Tokonomics REST API lets you proxy LLM requests through a unified metering layer and query real-time spend analytics — all from a single base URL. Every proxied call is automatically metered, tagged, and counted against your configured monthly budget so you always know exactly what you’re spending.

​
Base URL

All API requests are made to: 
https://tokonomics.ca

​
Authentication

Authenticate every request by passing your Tokonomics API key as a Bearer token in the Authorization header. All keys are prefixed with mk_ followed by 48 hex characters. 
Authorization: Bearer mk_your_key
Example: 
curl https://tokonomics.ca/analytics/summary \
  -H "Authorization: Bearer mk_your_key"
Keep your API key secret. Do not commit it to source control or expose it in client-side code. If a key is compromised, rotate it immediately from your Tokonomics dashboard.

​
Rate Limits

Every API response includes the following rate-limit headers:
HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed per minute for your plan
X-RateLimit-RemainingNumber of requests remaining in the current one-minute window
When you exceed your rate limit, the API returns a 429 Too Many Requests response. The response also includes a Retry-After header indicating how many seconds to wait before retrying.

​
Error Responses

All errors return a JSON body with error and message fields: 
{
  "error": "error_code",
  "message": "A human-readable description of what went wrong."
}
StatusMeaning
401Invalid or missing API key
429Rate limit exceeded or monthly budget cap reached
502Upstream provider error
A 429 response can indicate either a rate limit or that your account has reached its monthly budget cap. Check the message field to distinguish between the two cases.

​
Endpoints Summary

MethodPathDescription
POST/proxy/{provider}/{path}Proxy an LLM API call
GET/analytics/summaryCurrent month spend summary
GET/analytics/dailyDaily spend breakdown
GET/analytics/by-tagSpend grouped by tag
GET/analytics/eventsPaginated raw usage events
GET/healthHealth check (no auth required)

​
UsageEvent Schema

Every metered LLM call produces a UsageEvent record. You’ll encounter this object in the /analytics/events endpoint response.
​
id
string
Unique UUID identifier for the event. Example: "3f6a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
​
model
string
The model name as reported by the provider. Example: "gpt-4o"
​
provider
string
The provider slug. Example: "openai"
​
input_tokens
integer
Number of input (prompt) tokens consumed by the request.
​
output_tokens
integer
Number of output (completion) tokens generated by the model.
​
cache_read_tokens
integer
Number of tokens served from the provider’s prompt cache (read). Billed at a reduced rate where supported.
​
cache_creation_tokens
integer
Number of tokens written to the provider’s prompt cache. Billed at a premium where supported.
​
cost_usd
number
Total cost of the request in USD, calculated to 8 decimal places. Example: 0.00342100
​
latency_ms
integer
End-to-end request latency in milliseconds, from the time Tokonomics received your request to the time the provider response was fully received.
​
tags
object
Key-value pairs of custom tags attached to the request via the X-Metering-Tags header. Values are always strings. Example: {"team": "growth", "feature": "summarizer"}
​
created_at
string
ISO 8601 datetime when the event was recorded. Example: "2026-06-10T14:32:01.000Z"