GET /analytics/by-tag — AI Spend Grouped by Tag Key

Returns AI spend and request counts grouped by a custom tag key — such as team, feature, or tenant — over a week, month, or quarter.

The by-tag endpoint lets you slice your AI spend by any custom dimension you’ve been tracking with the X-Metering-Tags header. Pass a tag key — such as team, feature, or tenant_id — and get back a ranked breakdown of spend and request counts per tag value for the chosen period. Use this to run internal chargebacks, understand which product features are driving costs, or monitor per-tenant consumption.

Endpoint

GET https://tokonomics.ca/analytics/by-tag

Query Parameters

key · string · required

The tag key to group results by. This must match a key you’ve been setting in the X-Metering-Tags request header on your proxied calls.

Common values: team, feature, tenant_id

GET /analytics/by-tag?key=team

period · string · default: "month"

The time period to aggregate spend over. Must be one of:

Value	Description
week	Last 7 days
month	Current calendar month (default)
quarter	Current calendar quarter

GET /analytics/by-tag?key=team&period=quarter

Response Fields

key · string

The tag key that was used to group the results. Mirrors the key query parameter. Example: "team"

period · string

The aggregation period that was used. Mirrors the period query parameter. Example: "month"

groups · array

An array of spend groups, one per distinct tag value, sorted by spend descending.

Show groups fields

value · string

The tag value for this group. Example: "growth"

spend · number

Total spend in USD attributed to this tag value over the period. Example: 45.20

requests · integer

Total number of requests attributed to this tag value over the period. Example: 2300

Tag-based analytics require you to set tags on your proxy requests using the X-Metering-Tags header. Requests made without tags will not appear in any by-tag breakdown.

Example

Request

curl "https://tokonomics.ca/analytics/by-tag?key=team&period=month" \
  -H "Authorization: Bearer mk_your_key_here"

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