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

# Tag LLM Requests for Cost Attribution in Tokonomics

> Attach custom tags to every LLM call so you can break down AI spend by team, feature, environment, or any dimension your business needs.

Tagging lets you annotate every LLM request with metadata that matters to your business. When Tokonomics records a UsageEvent, it stores your tags alongside the token counts and cost. You can then query spend grouped by any tag key — making it straightforward to answer questions like "how much did the support chatbot cost this month?" or "what is each tenant spending on AI?"

## Metering headers

You attach tags to a request using three optional HTTP headers. All three are stripped by Tokonomics before the request is forwarded to the provider, so they never appear in your provider logs.

### `X-Metering-Tags`

A JSON object of arbitrary key-value pairs. Use this header when you want to attach multiple dimensions to a single request.

```text theme={null}
X-Metering-Tags: {"team":"growth","feature":"chatbot","env":"production"}
```

Both keys and values must be strings. Tokonomics stores each pair as a flat tag on the UsageEvent.

### `X-Feature-Name`

A shorthand header for tagging a single feature. Tokonomics stores the value as `{"feature": "<value>"}` on the UsageEvent. Use this header when `X-Metering-Tags` would be redundant for simple per-feature attribution.

```text theme={null}
X-Feature-Name: support-bot
```

### `X-Tenant-ID`

Identifies the end-customer on whose behalf the call is made. Tokonomics stores the value as `{"tenant_id": "<value>"}` on the UsageEvent, enabling per-customer cost breakdowns.

```text theme={null}
X-Tenant-ID: tenant_abc123
```

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl https://tokonomics.ca/proxy/openai/chat/completions \
    -H "Authorization: Bearer mk_your_key" \
    -H "X-Metering-Tags: {\"team\":\"growth\",\"feature\":\"chatbot\"}" \
    -H "X-Feature-Name: chatbot" \
    -H "X-Tenant-ID: tenant_abc123" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  ```python Python theme={null}
  import openai

  client = openai.OpenAI(
      api_key="sk_your_openai_key",
      base_url="https://tokonomics.ca/proxy/openai",
      default_headers={
          "Authorization": "Bearer mk_your_key",
          "X-Metering-Tags": '{"team":"growth","feature":"chatbot"}',
          "X-Feature-Name": "chatbot",
          "X-Tenant-ID": "tenant_abc123",
      },
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
  )
  print(response.choices[0].message.content)
  ```
</CodeGroup>

## Querying by tag

Once your requests are tagged, you can break down spend by any tag key using the Analytics by Tag endpoint:

```text theme={null}
GET /analytics/by-tag?key=team
```

This returns total spend grouped by each unique value of the `team` tag. You can scope the result to a time period using the `period` query parameter:

| Parameter | Values                     | Default |
| --------- | -------------------------- | ------- |
| `key`     | Any tag key you have used  | —       |
| `period`  | `week`, `month`, `quarter` | `month` |

For example, `GET /analytics/by-tag?key=feature&period=quarter` returns per-feature spend for the current quarter. See the full endpoint reference at [Analytics by Tag](/api-reference/analytics-by-tag).

## Best practices

<Accordion title="What tag keys should I use?">
  There are no reserved tag keys. A useful starting set covers the dimensions you already report on:

  * `team` — the engineering or business team responsible for the feature
  * `feature` — the product feature making the LLM call
  * `env` — `production`, `staging`, or `development`
  * `tenant_id` — your customer's identifier for multi-tenant apps
  * `product` — the top-level product area, useful when multiple teams share one account

  Keep key names consistent across your codebase. Mixed casing or synonyms (e.g. `team` vs `Team` vs `squad`) will produce separate buckets in analytics.
</Accordion>

<Accordion title="Can I use nested tags?">
  No. Tags are flat key-value pairs where both the key and value must be strings. If you need hierarchical grouping, encode the hierarchy in your key name — for example `{"product":"platform","team":"platform-infra"}` rather than trying to nest objects.
</Accordion>

<Accordion title="How many tags can I attach per request?">
  There is no documented limit on the number of tags per request. In practice, keep your tag set small and consistent — five to ten well-chosen keys produce far more actionable analytics than dozens of one-off labels.
</Accordion>