Skip to main content
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 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!"}]
  }'

​
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:
ParameterValuesDefault
keyAny tag key you have used—
periodweek, month, quartermonth
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

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