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 
curl -X GET \
  "https://<<META.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.
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".

Was this helpful?