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

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

```text theme={null}
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.

```text theme={null}
Authorization: Bearer mk_your_key
```

**Example:**

```bash theme={null}
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:

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

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

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

<ResponseField name="id" type="string">
  Unique UUID identifier for the event. Example: `"3f6a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"`
</ResponseField>

<ResponseField name="model" type="string">
  The model name as reported by the provider. Example: `"gpt-4o"`
</ResponseField>

<ResponseField name="provider" type="string">
  The provider slug. Example: `"openai"`
</ResponseField>

<ResponseField name="input_tokens" type="integer">
  Number of input (prompt) tokens consumed by the request.
</ResponseField>

<ResponseField name="output_tokens" type="integer">
  Number of output (completion) tokens generated by the model.
</ResponseField>

<ResponseField name="cache_read_tokens" type="integer">
  Number of tokens served from the provider's prompt cache (read). Billed at a reduced rate where supported.
</ResponseField>

<ResponseField name="cache_creation_tokens" type="integer">
  Number of tokens written to the provider's prompt cache. Billed at a premium where supported.
</ResponseField>

<ResponseField name="cost_usd" type="number">
  Total cost of the request in USD, calculated to 8 decimal places. Example: `0.00342100`
</ResponseField>

<ResponseField name="latency_ms" type="integer">
  End-to-end request latency in milliseconds, from the time Tokonomics received your request to the time the provider response was fully received.
</ResponseField>

<ResponseField name="tags" type="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"}`
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 datetime when the event was recorded. Example: `"2026-06-10T14:32:01.000Z"`
</ResponseField>