Sign in

v1

latestOpenAPI 3.1.02026-07-26269227514.8 KB

Get consumption analytics

Query credit or ACU consumption data for the authenticated team. Results are sourced from hourly-aggregated billing events and can be filtered by date range, product, model, and group.

The response shape depends on the team's billing strategy:

  • Credits-based teams receive prompt_credits and flex_credits in each row.
  • ACU-based teams receive billed_acus in each row.

Responses are cached for 1 hour. Use If-None-Match with a previously returned ETag to receive a 304 Not Modified when the data has not changed.

These endpoints are designed for periodic reporting and bulk export. They are not intended for real-time usage monitoring: data is hourly-aggregated and the rate limit is low (10 requests per hour per team).

get/api/v2alpha/analytics/consumption

Query parameters

start_datestring date required

Start of the date range (inclusive) in YYYY-MM-DD format.

end_datestring date required

End of the date range (inclusive) in YYYY-MM-DD format. The range must not exceed 90 days.

product'agent' required

Product to query consumption for.

granularity'daily' | 'monthly'

Time granularity for grouping results. When specified, each row includes a timestamp field. If omitted, results are aggregated across the entire date range.

group_bystring

Comma-separated list of dimensions to group results by. Supported dimensions:

  • user — includes user_id and user_email in each row
  • model_uid — includes model_uid in each row
  • ide — includes ide in each row
  • ide_version — includes ide_version in each row; requires ide to also be included
modelsstring

Comma-separated list of model UIDs to filter results to.

group_idstring

Filter results to users in a specific group. The service key must have access to this group.

user_idstring

Filter results to a specific user (auth UID).

page_sizeinteger

Maximum number of rows to return per page.

page_cursorstring

Opaque cursor from a previous response's pagination.next_page_cursor to fetch the next page.

Headers

If-None-Matchstring

ETag value from a previous response. If the data has not changed, the server returns 304 Not Modified.

Response

Consumption data returned successfully.

Example response

{
  "data": [
    {
      "timestamp": "2026-05-01",
      "user_email": "alice@example.com",
      "model_uid": "claude-4-sonnet",
      "ide": "windsurf",
      "ide_version": "1.0.0"
    }
  ]
}