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

# Attribute AI Costs to Teams, Features, and Tenants

> Use Tokonomics metering headers to tag every LLM call and then query spend broken down by team, feature, environment, or customer tenant.

When multiple teams, features, or customers share the same LLM budget, understanding who is spending what is the difference between informed decisions and guesswork. Tokonomics lets you attach structured metadata to every proxied request using HTTP headers. Those tags are stored alongside the usage record and are immediately queryable through the analytics API and dashboard.

## Tagging a request

Add one or more of the following headers to any request you send through Tokonomics. You can mix and match them on the same request.

| Header            | Format      | Purpose                                                                                             |
| ----------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `X-Metering-Tags` | JSON object | Arbitrary key-value pairs for team, feature, environment, or any other dimension                    |
| `X-Feature-Name`  | String      | Shorthand for a single feature name — equivalent to `{"feature":"your-value"}` in `X-Metering-Tags` |
| `X-Tenant-ID`     | String      | Your customer's identifier — used for per-tenant cost breakdowns in multi-tenant products           |

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

Tags are forward-compatible — you can add new keys at any time and they appear in analytics immediately without any configuration changes.

## Querying spend by tag

Use the `GET /analytics/by-tag` endpoint to retrieve spend aggregated by any tag key. Specify the key you want to group by and the time period.

```bash cURL theme={null}
curl "https://tokonomics.ca/api/analytics/by-tag?key=team&period=month" \
  -H "Authorization: Bearer mk_your_tokonomics_key"
```

**Sample response:**

```json theme={null}
{
  "key": "team",
  "period": "month",
  "groups": [
    {"value": "growth", "spend": 45.20, "requests": 2300},
    {"value": "support", "spend": 12.50, "requests": 890}
  ]
}
```

You can replace `team` with any key you use in `X-Metering-Tags`, or with the reserved keys `feature_name` (populated by `X-Feature-Name`) and `tenant_id` (populated by `X-Tenant-ID`).

Supported `period` values are `day`, `week`, `month`, and `custom` (combine with `start` and `end` query parameters in ISO 8601 format).

## Multi-tenant billing

If you build a product where each of your customers triggers LLM calls, set `X-Tenant-ID` to that customer's unique identifier on every request. Tokonomics tracks cost and usage per tenant automatically.

To retrieve a per-tenant breakdown, query:

```bash cURL theme={null}
curl "https://tokonomics.ca/api/analytics/by-tag?key=tenant_id&period=month" \
  -H "Authorization: Bearer mk_your_tokonomics_key"
```

The response lists each tenant ID alongside its spend and request count for the period. You can use this data to power usage-based billing, enforce per-customer budgets, or simply identify your heaviest-spending customers.

<Note>
  `X-Tenant-ID` values are stored as-is. Use a stable, opaque identifier — such as your internal customer UUID — rather than a mutable value like a company name.
</Note>

## Common tag schemas

<AccordionGroup>
  <Accordion title="By team">
    Tag requests with the team responsible for that feature or service. This gives you a clear per-team spend breakdown each month.

    ```json theme={null}
    {"team": "growth"}
    {"team": "engineering"}
    {"team": "support"}
    ```
  </Accordion>

  <Accordion title="By feature">
    Tag requests with the product feature that triggered the call. Use `X-Metering-Tags` for the full key-value form or `X-Feature-Name` as a shorthand when you only need a single feature label.

    ```json theme={null}
    {"feature": "chatbot"}
    {"feature": "document-summary"}
    {"feature": "email-draft"}
    ```

    Or using the shorthand header:

    ```text theme={null}
    X-Feature-Name: chatbot
    ```
  </Accordion>

  <Accordion title="By environment">
    Separate production spend from staging and development spend so you know exactly how much of your budget is attributable to live traffic.

    ```json theme={null}
    {"env": "production"}
    {"env": "staging"}
    {"env": "development"}
    ```
  </Accordion>

  <Accordion title="By customer">
    For multi-tenant products, use `X-Tenant-ID` to attribute every call to the customer who triggered it. Avoid using mutable values like company names; prefer stable internal IDs.

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

    You can also combine it with `X-Metering-Tags` to capture additional context alongside the tenant:

    ```json theme={null}
    {"team": "platform", "env": "production"}
    ```
  </Accordion>
</AccordionGroup>

For the full analytics API reference, see [Analytics by Tag](/api-reference/analytics-by-tag). For a complete list of supported tagging headers, see [Tagging](/concepts/tagging).