Get Token Usage Over Time

Get token usage over time across a date range.

Returns token usage bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, or speed. Available to organizations on a Claude Enterprise plan. Requires an API key with the read:analytics scope.

get/v1/organizations/analytics/usage_report?beta=true

Query parameters

starting_atstring date-time required

Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.

ending_atstring date-time nullable

End of range, exclusive. When omitted, defaults to the earlier of now and starting_at + 31 days. The range may span at most 31 days.

bucket_width'1d' | '1h' | '1m'

Time bucket granularity.

products[]BetaAnalyticsProductFilter[] nullable

Product surfaces to include. Defaults to all products. Use group_by[]=product to break out per-product values.

models[]string[] nullable

Models to include. Defaults to all models. Use group_by[]=model to break out per-model values.

context_windows[]BetaMessagesUsageReportContextWindow[] nullable

Filter to specific context-window pricing tiers. Use group_by[]=context_window to break out per-tier values.

inference_geos[]BetaInferenceGeoFilter[] nullable

Filter to specific inference regions. not_available matches rows where the region is unset. Use group_by[]=inference_geo to break out per-region values.

speeds[]string[] nullable

Filter to fast or standard inference mode. Use group_by[]=speed to break out per-mode values.

slack_channel_ids[]string[] nullable

Filter to usage originating from specific Slack channels. Use group_by[]=slack_channel_id to break out per-channel values.

[
  "C0123ABCDEF"
]

rbac_group_ids[]string[] nullable

Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (rbac_group_...) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.

[
  "rbac_group_012rppKaSVsmTo6NqRDXQXNF"
]

user_ids[]string[] nullable

Filter to specific users by tagged user ID.

limitinteger nullable

Maximum number of time buckets per page. Defaults and caps vary by bucket_width (1d: default 7, max 31; 1h: default 24, max 168; 1m: default 60, max 256).

pagestring nullable

Opaque cursor from a previous response's next_page field.

group_by[]string[] nullable

Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values.

Headers

x-api-keystring nullable

Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

Response

Successful Response

data_refreshed_atstring date-time nullable required

RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case every bucket's results list is empty. Buckets beyond this watermark are incomplete; for stable results, set ending_at to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).

has_moreboolean required

Whether another page is available. When true, pass next_page as the page parameter to fetch it.

next_pagestring nullable required

Opaque cursor for the next page, or null when has_more is false. Pass it as the page parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page.

organization_idstring required

ID of the Organization.

Example response

{
  "data": [
    {
      "results": [
        {
          "model": "claude-opus-5",
          "product": "chat",
          "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
          "server_tool_use": {
            "web_search_requests": 10
          },
          "slack_channel_id": "C0123ABCDEF",
          "speed": "fast"
        }
      ]
    }
  ],
  "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}

Get Token Usage Over Time

Query parameters

Headers

Response

Example response

Changes