AI usage: List

Last updated September 18, 2026Open markdown version

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, feature, story, user, or action, 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
story_id	Optional Only return runtime usage from AI actions and AI agents in the specified story. Non-admin users only see usage from teams they belong to, so requesting a story outside those teams returns a zeroed response.	No	Integer
user_id	Optional Only return usage initiated by the specified user. Non-admin users can only attribute usage to users they can see, so requesting any other user returns a zeroed response.	No	Integer
action_id	Optional Only return runtime usage from the specified AI action or AI agent. An AI action used as a tool by an agent reports its own usage under its own ID, not the agent's. Non-admin users only see usage from teams they belong to, so requesting an action outside those teams returns a zeroed response.	No	Integer
group_by	Optional Break the response into per-bucket groups along one dimension: `model`, `provider`, `team`, `feature`, `story`, `user`, `action`, or `day`. When omitted, only the `totals` are returned.	No	String

curl -X GET \
  "https://<tenant-domain>/api/v1/ai_usage?relative_date=30%20days&group_by=model" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

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.
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.
story_id, story_name	Present when `group_by=story`: the story identifier and name. `story_id` is `null` for usage that didn't run inside a story, such as Workbench, and for usage from stories you can't see.
user_id, user_email, user_name, is_service_account	Present when `group_by=user`: the identifier, email, name, and service account flag of the user who initiated the usage. `user_id` is `null` for usage with no initiating user, such as AI actions and AI agents running in a story, and for usage initiated by users you can't see. `user_email` is `null` for service accounts.
action_id, action_name, story_id	Present when `group_by=action`: the AI action or AI agent identifier and name, plus the identifier of the story it belongs to. `action_id` is `null` for usage that didn't come from an AI action or AI agent, and for usage from actions you can't see.
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)

{
  "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)

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

When grouping by story, user, or action, usage that you can see but whose story, user, or action you can't — for example, team-less usage from an AI action in another team's story — is folded into the null bucket rather than identifying the record.