Get Per-User Token Usage

----
-title: Get Per-User Token Usage
-url: https://platform.claude.com/docs/en/api/admin/analytics/usage/list_by_user
----
+# Get Per-User Token Usage
 
-## Get Per-User Token Usage
+**GET** `/v1/organizations/analytics/user_usage_report`
 
-**get** `/v1/organizations/analytics/user_usage_report`
-
 Get per-user token usage across a date range.
 
 Returns one row per user, ranked by the chosen token metric. Use this 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. When set, each row's `starting_at` and `ending_at` are populated and one actor may span several rows (one per time bucket with usage). The time bucket counts toward `limit`, so one page can return multiple rows for the same actor. `ending_at` is required when `bucket_width` is set, and with `bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the full `[starting_at, ending_at)` range.

 
   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
+
 - `exclude_deleted_users: optional boolean`
 
   If true, omit rows for users who are deleted (`deleted: true`). A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual.
 
+  default: false
+
 - `group_by: optional array of "context_window" or "inference_geo" or "model" or 4 more`
 
   Break each actor's row out by the given dimensions. Accepts the same values as the bucketed `/usage_report` endpoint. `limit` bounds (actor × time bucket × dimension) rows — with dimensions or `bucket_width` present, one actor may span several rows.
 
+  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"`

 
   Number of rows per page (1-1000, default 20). One row per actor unless `group_by[]` or `bucket_width` splits an actor across rows; `cost_type`/`token_type` fan-out rows (cost endpoint only) are the exception — they do not count toward this limit, so `data` can exceed it.
 
+  default: 20, maximum: 1000, 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
+
 - `order: optional "asc" or "desc"`
 
   Sort direction. Defaults to `desc`.
 
+  default: desc
+
   - `"asc"`
 
   - `"desc"`

 
   Metric to rank actors by. Defaults to `total_tokens`.
 
+  default: total_tokens
+
   - `"output_tokens"`
 
   - `"requests"`

 
   Product surfaces to include. Defaults to all products. 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
 
-- `UserUsage object { data, data_refreshed_at, has_more, 2 more }`
+## Returns
 
-  - `data: array of object { actor, cache_creation, cache_read_input_tokens, 14 more }`
+- `UserUsage object`
 
+  - `data: array of object`
+
     Rows for this page, ranked by `order_by` in the `order` direction. One row per user, or several per user when `group_by[]` or `bucket_width` breaks that user's usage or cost out across rows. Rows split out by `cost_type` or `token_type` (cost endpoint only) stay adjacent and are ranked as one unit.
 
     - `actor: AnalyticsUserActor`

 
         Actor type. Always `"user_actor"`.
 
-        - `"user_actor"`
-
       - `user_id: string`
 
         Tagged user ID.
 
-    - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
+    - `cache_creation: object`
 
       The number of input tokens for cache creation.
 

 
       End of the row's UTC time bucket (exclusive), as an RFC 3339 timestamp; equal to `starting_at` plus one `bucket_width`. Null unless `bucket_width` is set.
 
+      format: date-time
+
     - `inference_geo: "global" or "us" or null`
 
       Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches).

 
       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 row's UTC time bucket (inclusive), as an RFC 3339 timestamp. Null unless `bucket_width` is set; without `bucket_width`, each row aggregates the full requested range.
 
+      format: date-time
+
     - `total_tokens: number`
 
       Total token count across all token types. This is the value the default order_by='total_tokens' sorts on.

 
     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 `data` is empty. Data beyond this watermark is 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/user_usage_report \
     -H 'anthropic-version: 2023-06-01' \
     -H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
 ```
 
-#### Response
+### Response (200)
 
 ```json
 {