Skip to main content
The proxy endpoint forwards your LLM requests to the upstream provider while transparently metering token usage and cost. You send the exact same request body you would send directly to the provider — Tokonomics intercepts it, records the usage event, and streams the provider’s response back to you with no added latency beyond the metering overhead. Endpoint 
POST https://tokonomics.ca/proxy/{provider}/{path}

​
Path Parameters

​
provider
string
required
The LLM provider slug identifying which upstream API to route the request to. Must be one of:
SlugProvider
openaiOpenAI
anthropicAnthropic
deepseekDeepSeek
geminiGoogle Gemini
mistralMistral AI
xaixAI (Grok)
cohereCohere
groqGroq
togetherTogether AI
​
path
string
required
The upstream API path to forward the request to. This is the provider-native path — for example, chat/completions for OpenAI or messages for Anthropic.Examples:
  • OpenAI: chat/completions
  • Anthropic: messages
  • Gemini: models/gemini-2.0-flash:generateContent

​
Request Headers

​
Authorization
string
required
Your Tokonomics API key in Bearer token format.
Authorization: Bearer mk_your_tokonomics_key
​
Content-Type
string
required
Must be application/json.
​
X-Metering-Tags
string
A JSON-encoded object of custom key-value tags to attach to the usage event. Use this to attribute spend to teams, features, or any other dimension you want to query in analytics.
X-Metering-Tags: {"team": "growth", "feature": "summarizer"}
​
X-Feature-Name
string
Shorthand for tagging a single feature name. Sets the feature tag on the usage event. Equivalent to passing {"feature": "your-feature"} in X-Metering-Tags.
X-Feature-Name: email-drafter
​
X-Tenant-ID
string
A customer tenant identifier to attach to the usage event. Sets the tenant_id tag, enabling per-tenant spend breakdowns in analytics.
X-Tenant-ID: acme-corp

​
Request Body

Pass the provider’s native request body unchanged as a JSON object. Tokonomics forwards your request body to the upstream provider without modification.
You do not need to include your upstream provider API key in the request body. Tokonomics injects it server-side using the credentials you configured in your dashboard.
Example — OpenAI chat completion: 
{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Summarize the key points of the Tokonomics docs."}
  ],
  "max_tokens": 512,
  "stream": true
}

​
Response

Tokonomics streams the provider’s response directly back to you. The response body and status code are the provider’s native response — no transformation is applied. The following additional headers are injected by Tokonomics:
HeaderDescription
X-Metering-LatencyTotal round-trip latency as a string, e.g. "342ms"
X-RateLimit-LimitYour plan’s request-per-minute limit
X-RateLimit-RemainingRemaining requests in the current one-minute window

​
Error Responses

StatusMeaning
401Invalid or missing Tokonomics API key
429Rate limit exceeded or monthly budget cap reached — check the Retry-After header
502The upstream provider returned an error or was unreachable
401 response body: 
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
When a 429 is returned due to budget cap, your requests will be blocked until the budget resets at the start of the next calendar month or you increase your budget in the dashboard.

​
Full Example

curl -X POST "https://tokonomics.ca/proxy/openai/chat/completions" \
  -H "Authorization: Bearer mk_your_tokonomics_key" \
  -H "Content-Type: application/json" \
  -H "X-Metering-Tags: {\"team\": \"growth\", \"feature\": \"summarizer\"}" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is Tokonomics?"}
    ],
    "max_tokens": 256
  }'