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

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

```text theme={null}
GET https://tokonomics.ca/analytics/by-tag
```

## Query Parameters

<ParamField query="key" type="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`

  ```text theme={null}
  GET /analytics/by-tag?key=team
  ```
</ParamField>

<ParamField query="period" type="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         |

  ```text theme={null}
  GET /analytics/by-tag?key=team&period=quarter
  ```
</ParamField>

## Response Fields

<ResponseField name="key" type="string">
  The tag key that was used to group the results. Mirrors the `key` query parameter. Example: `"team"`
</ResponseField>

<ResponseField name="period" type="string">
  The aggregation period that was used. Mirrors the `period` query parameter. Example: `"month"`
</ResponseField>

<ResponseField name="groups" type="array">
  An array of spend groups, one per distinct tag value, sorted by `spend` descending.

  <Expandable title="groups fields">
    <ResponseField name="value" type="string">
      The tag value for this group. Example: `"growth"`
    </ResponseField>

    <ResponseField name="spend" type="number">
      Total spend in USD attributed to this tag value over the period. Example: `45.20`
    </ResponseField>

    <ResponseField name="requests" type="integer">
      Total number of requests attributed to this tag value over the period. Example: `2300`
    </ResponseField>
  </Expandable>
</ResponseField>

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

## Example

<CodeGroup>
  ```bash Request theme={null}
  curl "https://tokonomics.ca/analytics/by-tag?key=team&period=month" \
    -H "Authorization: Bearer mk_your_key_here"
  ```

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