POST /proxy/{provider}/{path} — Proxy LLM Requests

Proxy LLM requests through Tokonomics for automatic cost metering. Supports OpenAI, Anthropic, DeepSeek, Gemini, Mistral, xAI, Cohere, Groq, and Together.

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:

Slug	Provider
openai	OpenAI
anthropic	Anthropic
deepseek	DeepSeek
gemini	Google Gemini
mistral	Mistral AI
xai	xAI (Grok)
cohere	Cohere
groq	Groq
together	Together 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:

Header	Description
X-Metering-Latency	Total round-trip latency as a string, e.g. "342ms"
X-RateLimit-Limit	Your plan’s request-per-minute limit
X-RateLimit-Remaining	Remaining requests in the current one-minute window

Error Responses

Status	Meaning
401	Invalid or missing Tokonomics API key
429	Rate limit exceeded or monthly budget cap reached — check the Retry-After header
502	The 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

OpenAI Chat Completion

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
  }'

curl -X POST "https://tokonomics.ca/proxy/anthropic/messages" \
  -H "Authorization: Bearer mk_your_tokonomics_key" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: acme-corp" \
  -d '{
    "model": "claude-opus-4-5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Explain prompt caching in one sentence."}
    ]
  }'