Tokonomics API Reference — Overview and Authentication

Base URL, authentication, rate limits, and error codes for the Tokonomics REST API. Everything you need before making your first request.

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:

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed per minute for your plan
X-RateLimit-Remaining	Number 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."
}

Status	Meaning
401	Invalid or missing API key
429	Rate limit exceeded or monthly budget cap reached
502	Upstream 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

Method	Path	Description
POST	/proxy/{provider}/{path}	Proxy an LLM API call
GET	/analytics/summary	Current month spend summary
GET	/analytics/daily	Daily spend breakdown
GET	/analytics/by-tag	Spend grouped by tag
GET	/analytics/events	Paginated raw usage events
GET	/health	Health 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"