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.

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.

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.

X-Tenant-ID: tenant_abc123

Examples

curl

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!"}]
  }'

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)

Querying by tag

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

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.

Best practices

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.

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.

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.