Get Token Usage Over Time

----
-title: Get Token Usage Over Time
-url: https://platform.claude.com/docs/en/api/admin/analytics/usage/list
----
+# Get Token Usage Over Time
 
-## Get Token Usage Over Time
+**GET** `/v1/organizations/analytics/usage_report`
 
-**get** `/v1/organizations/analytics/usage_report`
-
 Get token usage over time across a date range.
 
 Returns token usage bucketed by minute, hour, or day, optionally broken

 Available to organizations on a Claude Enterprise plan. Requires an API
 key with the `read:analytics` scope.
 
-### Query Parameters
+## Query parameters
 
 - `starting_at: string`
 
   Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
 
+  format: date-time
+
 - `bucket_width: optional "1d" or "1h" or "1m"`
 
   Time bucket granularity.
 
+  default: 1d
+
   - `"1d"`
 
   - `"1h"`

 
   Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
 
+  maxItems: 100
+
   - `"0-200k"`
 
   - `"200k-1M"`

 
   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.
 
+  format: date-time
+
 - `group_by: optional array of "context_window" or "inference_geo" or "model" or 4 more`
 
   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.
 
+  maxItems: 100
+
   - `"context_window"`
 
   - `"inference_geo"`

 
   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.
 
+  maxItems: 100
+
   - `"global"`
 
   - `"not_available"`

 
   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).
 
+  minimum: 1
+
 - `models: optional array of string`
 
   Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
 
+  maxItems: 100
+
 - `page: optional string`
 
   Opaque cursor from a previous response's `next_page` field.

 
   Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it.
 
+  maxItems: 100
+
 - `rbac_group_ids: optional array of string`
 
   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.
 
+  maxItems: 100
+
 - `slack_channel_ids: optional array of string`
 
   Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
 
+  maxItems: 100
+
 - `speeds: optional array of "fast" or "standard"`
 
   Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
 
+  maxItems: 100
+
   - `"fast"`
 
   - `"standard"`

 
   Filter to specific users by tagged user ID.
 
-### Returns
+  maxItems: 100
 
-- `UsageBucket object { data, data_refreshed_at, has_more, 2 more }`
+## Returns
 
-  - `data: array of object { ending_at, results, starting_at }`
+- `UsageBucket object`
 
+  - `data: array of object`
+
     Time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no data (their `results` list is empty). A page holds at most `limit` buckets.
 
     - `ending_at: string`

 
       End of the time bucket (exclusive) in RFC 3339 format.
 
-    - `results: array of object { cache_creation, cache_read_input_tokens, context_window, 10 more }`
+      format: date-time
 
+    - `results: array of object`
+
       Rows for this time bucket. Empty when the bucket has no data; otherwise a single combined row when `group_by[]` is omitted, or one row per group (subject to the per-bucket group cap described on the `group_by[]` parameter).
 
-      - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
+      - `cache_creation: object`
 
         The number of input tokens for cache creation.
 

 
         Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
 
-      - `server_tool_use: object { web_search_requests }`
+      - `server_tool_use: object`
 
         Server-side tool usage metrics.
 

 
       Start of the time bucket (inclusive) in RFC 3339 format.
 
+      format: date-time
+
   - `data_refreshed_at: string or null`
 
     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).
 
+    format: date-time
+
   - `has_more: boolean`
 
     Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it.

 
     ID of the Organization.
 
-### Example
+## Example
 
-```http
+```bash
 curl https://api.anthropic.com/v1/organizations/analytics/usage_report \
     -H 'anthropic-version: 2023-06-01' \
     -H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
 ```
 
-#### Response
+### Response (200)
 
 ```json
 {