--- title: List url: https://www.tines.com/stories/docs/api/ai-usage/list/ updated: 2026-06-05T09:01:03+00:00 description: Retrieve aggregated AI usage for the tenant, including token counts, credits consumed, and cost in US dollars. Results can be filtered by time range, team, model, provider, or feature, and optionally grouped by one of these dimensions. --- *[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/stories/docs/llms.txt) › [Tines API](https://www.tines.com/stories/docs/api/llms.txt) › [AI usage](https://www.tines.com/llm/stories/docs/api/ai-usage.md)* # List *[View on tines.com](https://www.tines.com/stories/docs/api/ai-usage/list/)* ## Description Retrieve aggregated AI usage for the tenant, including token counts, credits consumed, and cost in US dollars. Results can be filtered by time range, team, model, provider, or feature, and optionally grouped by one of these dimensions. Admins see usage across the entire tenant. Non-admin users see usage from teams they belong to, plus usage rows not attributed to any team. ## Request HTTP Method: **GET** | Parameter | Description | Required | Type | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | relative_date | **Optional** Predefined time window relative to now, for example `today`, `yesterday`, `7 days`, `30 days`, `3 months`, or `1 year`. Defaults to `30 days`. Cannot be combined with `start_date` and `end_date`. | No | String | | start_date | **Optional** ISO 8601 timestamp for the start of a custom time window. Must be paired with `end_date`. | No | String | | end_date | **Optional** ISO 8601 timestamp for the end of a custom time window. Must be paired with `start_date`, must be after `start_date`, and the window cannot exceed one year. | No | String | | team_id | **Optional** Only return usage attributed to the specified team. Non-admin users requesting usage for a team they don't belong to will receive a zeroed response. | No | Integer | | model_id | **Optional** Only return usage attributed to the specified model. | No | String | | provider_id | **Optional** Only return usage attributed to the specified provider. | No | Integer | | feature | **Optional** Only return usage attributed to the specified feature: `workbench`, `workbench_storyboard`, `ai_agents`, or `other`. | No | String | | group_by | **Optional** Break the response into per-bucket groups along one dimension: `model`, `provider`, `team`, `feature`, or `day`. When omitted, only the `totals` are returned. | No | String | ```bash curl -X GET \ "https:///api/v1/ai_usage?relative_date=30%20days&group_by=model" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request returns a JSON object summarizing aggregate AI usage over the requested window. When `group_by` is supplied, the response also includes a `groups` array, with one bucket per grouping key. ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------------------- | | range | The resolved time window. Contains `start` and `end` as ISO 8601 timestamps. | | totals | Aggregate usage across the entire window. See [Bucket fields](#bucket-fields). | | group_by | Echoes the `group_by` parameter when provided. Omitted from the response when `group_by` is not set. | | groups | An array of usage buckets, one per grouping key. Omitted when `group_by` is not set. | #### Bucket fields Each bucket in `totals` and `groups` shares the same shape. Group buckets additionally include the grouping key(s) for that bucket. | Parameter | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | input_tokens | Total input tokens sent to the model in this bucket. | | cached_read_input_tokens | Total input tokens served from the model's prompt cache. | | cached_write_input_tokens | Total input tokens written to the model's prompt cache. | | output_tokens | Total output tokens generated by the model. | | credits_used | Total Tines AI credits consumed. | | billed_cost | Total cost as an object with `currency` (for example, `usd`) and `amount` (a string formatted to two decimal places, for example, `"184.20"`). | | usage_count | Number of individual AI usage events rolled up into this bucket. | | model_id | Present when `group_by=model`: the model identifier for this bucket. | | provider_id, provider_name | Present when `group_by=provider`: the provider identifier and display name for this bucket. | | team_id, team_name | Present when `group_by=team`: the team identifier and name. `team_id` is `null` for usage not attributed to a team. | | feature | Present when `group_by=feature`: one of `workbench`, `workbench_storyboard`, `ai_agents`, or `other`. The `other` bucket covers usage that doesn't map to one of these customer-facing features. | | day | Present when `group_by=day`: the ISO 8601 date for this bucket. | ### Sample response (ungrouped) ```json { "range": { "start": "2026-04-12T00:00:00Z", "end": "2026-05-12T00:00:00Z" }, "totals": { "input_tokens": 1245000, "cached_read_input_tokens": 420000, "cached_write_input_tokens": 80000, "output_tokens": 312000, "credits_used": 18420, "billed_cost": { "currency": "usd", "amount": "184.20" }, "usage_count": 1284 } } ``` ### Sample response (grouped by model) ```json { "range": { "start": "2026-04-12T00:00:00Z", "end": "2026-05-12T00:00:00Z" }, "totals": { "input_tokens": 1245000, "cached_read_input_tokens": 420000, "cached_write_input_tokens": 80000, "output_tokens": 312000, "credits_used": 18420, "billed_cost": { "currency": "usd", "amount": "184.20" }, "usage_count": 1284 }, "group_by": "model", "groups": [ { "input_tokens": 845000, "cached_read_input_tokens": 380000, "cached_write_input_tokens": 60000, "output_tokens": 210000, "credits_used": 12300, "billed_cost": { "currency": "usd", "amount": "123.00" }, "usage_count": 812, "model_id": "claude-sonnet-4-6" }, { "input_tokens": 400000, "cached_read_input_tokens": 40000, "cached_write_input_tokens": 20000, "output_tokens": 102000, "credits_used": 6120, "billed_cost": { "currency": "usd", "amount": "61.20" }, "usage_count": 472, "model_id": "gpt-4o" } ] } ``` ### Time windows - Use `relative_date` for a rolling predefined window. The window ends at the current time and starts the corresponding duration in the past. Accepted values are `today`, `yesterday`, or a count followed by `day`, `week`, `month`, or `year` (singular or plural), for example `7 days` or `1 year`. - Use `start_date` and `end_date` for a custom window. Both must be valid ISO 8601 timestamps, `end_date` must be later than `start_date`, and the window cannot exceed one year. - `relative_date` and the `start_date`/`end_date` pair are mutually exclusive — supplying both returns a 400 response. ### Grouping When `group_by` is omitted, only `range` and `totals` are returned. When provided, the response additionally contains: - `group_by`: echoes the requested dimension. - `groups`: one bucket per distinct grouping key, each with the same usage fields as `totals` plus the key(s) for that bucket. A `null` grouping key is preserved — for example, when grouping by `team`, usage not attributed to a team appears as a bucket with `team_id: null`. When grouping by `feature`, usage that doesn't map to a customer-facing feature is collected under a bucket with `feature: "other"`.