Skip to main content
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.
HeaderFormatPurpose
X-Metering-TagsJSON objectArbitrary key-value pairs for team, feature, environment, or any other dimension
X-Feature-NameStringShorthand for a single feature name — equivalent to {"feature":"your-value"} in X-Metering-Tags
X-Tenant-IDStringYour customer’s identifier — used for per-tenant cost breakdowns in multi-tenant products
cURL
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.
cURL
curl "https://tokonomics.ca/api/analytics/by-tag?key=team&period=month" \
  -H "Authorization: Bearer mk_your_tokonomics_key"
Sample response: 
{
  "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:
cURL
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.
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.

​
Common tag schemas

Tag requests with the team responsible for that feature or service. This gives you a clear per-team spend breakdown each month.
{"team": "growth"}
{"team": "engineering"}
{"team": "support"}
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.
{"feature": "chatbot"}
{"feature": "document-summary"}
{"feature": "email-draft"}
Or using the shorthand header:
X-Feature-Name: chatbot
Separate production spend from staging and development spend so you know exactly how much of your budget is attributable to live traffic.
{"env": "production"}
{"env": "staging"}
{"env": "development"}
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.
X-Tenant-ID: tenant_abc123
You can also combine it with X-Metering-Tags to capture additional context alongside the tenant:
{"team": "platform", "env": "production"}
For the full analytics API reference, see Analytics by Tag. For a complete list of supported tagging headers, see Tagging.