Get Per-User Token Usage changedapi/admin/analytics/usage/list_by_user
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+51added
Lines−22removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits6to this page, all time
# Get Per-User Token Usage ## Query parameters ## Returns ## Example ### Response (200) ## Get Per-User Token Usage ### Query Parameters ### Returns ### Example #### Response
The whole hunk
from line 1, old and new numbered
/
from line 1
1---
2title: Get Per-User Token Usage
3url: https://platform.claude.com/docs/en/api/admin/analytics/usage/list_by_user
4---
1# Get Per-User Token Usage
52
6## Get Per-User Token Usage
3**GET** `/v1/organizations/analytics/user_usage_report`
74
8**get** `/v1/organizations/analytics/user_usage_report`
9
105Get per-user token usage across a date range.
116
127Returns one row per user, ranked by the chosen token metric. Use this to
from line 12
1712organizations on a Claude Enterprise plan. Requires an API key with the
1813`read:analytics` scope.
1914
20### Query Parameters
15## Query parameters
2116
2217- `starting_at: string`
2318
2419 Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
2520
21 format: date-time
22
2623- `bucket_width: optional "1d" or "1h" or "1m"`
2724
2825 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.
from line 34
3734
3835 Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
3936
37 maxItems: 100
38
4039 - `"0-200k"`
4140
4241 - `"200k-1M"`
from line 44
4544
4645 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.
4746
47 format: date-time
48
4849- `exclude_deleted_users: optional boolean`
4950
5051 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.
5152
53 default: false
54
5255- `group_by: optional array of "context_window" or "inference_geo" or "model" or 4 more`
5356
5457 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.
5558
59 maxItems: 100
60
5661 - `"context_window"`
5762
5863 - `"inference_geo"`
from line 76
7176
7277 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.
7378
79 maxItems: 100
80
7481 - `"global"`
7582
7683 - `"not_available"`
from line 88
8188
8289 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.
8390
91 default: 20, maximum: 1000, minimum: 1
92
8493- `models: optional array of string`
8594
8695 Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
8796
97 maxItems: 100
98
8899- `order: optional "asc" or "desc"`
89100
90101 Sort direction. Defaults to `desc`.
91102
103 default: desc
104
92105 - `"asc"`
93106
94107 - `"desc"`
from line 110
97110
98111 Metric to rank actors by. Defaults to `total_tokens`.
99112
113 default: total_tokens
114
100115 - `"output_tokens"`
101116
102117 - `"requests"`
from line 128
113128
114129 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.
115130
131 maxItems: 100
132
116133- `rbac_group_ids: optional array of string`
117134
118135 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.
119136
137 maxItems: 100
138
120139- `slack_channel_ids: optional array of string`
121140
122141 Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
123142
143 maxItems: 100
144
124145- `speeds: optional array of "fast" or "standard"`
125146
126147 Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
127148
149 maxItems: 100
150
128151 - `"fast"`
129152
130153 - `"standard"`
from line 156
133156
134157 Filter to specific users by tagged user ID.
135158
136### Returns
159 maxItems: 100
137160
138- `UserUsage object { data, data_refreshed_at, has_more, 2 more }`
161## Returns
139162
140 - `data: array of object { actor, cache_creation, cache_read_input_tokens, 14 more }`
163- `UserUsage object`
141164
165 - `data: array of object`
166
142167 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.
143168
144169 - `actor: AnalyticsUserActor`
from line 186
161186
162187 Actor type. Always `"user_actor"`.
163188
164 - `"user_actor"`
165
166189 - `user_id: string`
167190
168191 Tagged user ID.
169192
170 - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
193 - `cache_creation: object`
171194
172195 The number of input tokens for cache creation.
173196
from line 218
195218
196219 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.
197220
221 format: date-time
222
198223 - `inference_geo: "global" or "us" or null`
199224
200225 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).
from line 248
223248
224249 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`).
225250
226 - `server_tool_use: object { web_search_requests }`
251 - `server_tool_use: object`
227252
228253 Server-side tool usage metrics.
229254
from line 272
247272
248273 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.
249274
275 format: date-time
276
250277 - `total_tokens: number`
251278
252279 Total token count across all token types. This is the value the default order_by='total_tokens' sorts on.
from line 286
259286
260287 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).
261288
289 format: date-time
290
262291 - `has_more: boolean`
263292
264293 Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it.
from line 300
271300
272301 ID of the Organization.
273302
274### Example
303## Example
275304
276```http
305```bash
277306curl https://api.anthropic.com/v1/organizations/analytics/user_usage_report \
278307 -H 'anthropic-version: 2023-06-01' \
279308 -H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
280309```
281310
282#### Response
311### Response (200)
283312
284313```json
285314{
No line in this hunk matches that.