> ## Documentation Index
> Fetch the complete documentation index at: https://tokonomics.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

```text theme={null}
POST https://tokonomics.ca/proxy/{provider}/{path}
```

## Path Parameters

<ParamField path="provider" type="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   |
</ParamField>

<ParamField path="path" type="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`
</ParamField>

## Request Headers

<ParamField header="Authorization" type="string" required>
  Your Tokonomics API key in Bearer token format.

  ```text theme={null}
  Authorization: Bearer mk_your_tokonomics_key
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="X-Metering-Tags" type="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.

  ```text theme={null}
  X-Metering-Tags: {"team": "growth", "feature": "summarizer"}
  ```
</ParamField>

<ParamField header="X-Feature-Name" type="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`.

  ```text theme={null}
  X-Feature-Name: email-drafter
  ```
</ParamField>

<ParamField header="X-Tenant-ID" type="string">
  A customer tenant identifier to attach to the usage event. Sets the `tenant_id` tag, enabling per-tenant spend breakdowns in analytics.

  ```text theme={null}
  X-Tenant-ID: acme-corp
  ```
</ParamField>

## 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.

<Note>
  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.
</Note>

**Example — OpenAI chat completion:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash OpenAI Chat Completion theme={null}
  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
    }'
  ```

  ```bash Anthropic Messages theme={null}
  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."}
      ]
    }'
  ```
</CodeGroup>