Usage changedapi/admin/analytics/usage
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+111added
Lines−40removed
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
### Query parameters #### Response (200) ### Query parameters #### Response (200) ## Domain types ### Query Parameters #### Response ### Query Parameters #### Response ## Domain Types
The whole hunk
from line 1, old and new numbered
/
from line 1
1---
2title: Usage
3url: https://platform.claude.com/docs/en/api/admin/analytics/usage
4---
5
61# Usage
72
83## Get Token Usage Over Time
94
10**get** `/v1/organizations/analytics/usage_report`
5**GET** `/v1/organizations/analytics/usage_report`
116
127Get token usage over time across a date range.
138
from line 11
1611Available to organizations on a Claude Enterprise plan. Requires an API
1712key with the `read:analytics` scope.
1813
19### Query Parameters
14### Query parameters
2015
2116- `starting_at: string`
2217
2318 Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
2419
20 format: date-time
21
2522- `bucket_width: optional "1d" or "1h" or "1m"`
2623
2724 Time bucket granularity.
2825
26 default: 1d
27
2928 - `"1d"`
3029
3130 - `"1h"`
from line 35
3635
3736 Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
3837
38 maxItems: 100
39
3940 - `"0-200k"`
4041
4142 - `"200k-1M"`
from line 45
4445
4546 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.
4647
48 format: date-time
49
4750- `group_by: optional array of "context_window" or "inference_geo" or "model" or 4 more`
4851
4952 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.
5053
54 maxItems: 100
55
5156 - `"context_window"`
5257
5358 - `"inference_geo"`
from line 71
6671
6772 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.
6873
74 maxItems: 100
75
6976 - `"global"`
7077
7178 - `"not_available"`
from line 83
7683
7784 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).
7885
86 minimum: 1
87
7988- `models: optional array of string`
8089
8190 Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
8291
92 maxItems: 100
93
8394- `page: optional string`
8495
8596 Opaque cursor from a previous response's `next_page` field.
from line 99
8899
89100 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.
90101
102 maxItems: 100
103
91104- `rbac_group_ids: optional array of string`
92105
93106 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.
94107
108 maxItems: 100
109
95110- `slack_channel_ids: optional array of string`
96111
97112 Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
98113
114 maxItems: 100
115
99116- `speeds: optional array of "fast" or "standard"`
100117
101118 Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
102119
120 maxItems: 100
121
103122 - `"fast"`
104123
105124 - `"standard"`
from line 127
108127
109128 Filter to specific users by tagged user ID.
110129
130 maxItems: 100
131
111132### Returns
112133
113- `UsageBucket object { data, data_refreshed_at, has_more, 2 more }`
134- `UsageBucket object`
114135
115 - `data: array of object { ending_at, results, starting_at }`
136 - `data: array of object`
116137
117138 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.
118139
from line 141
120141
121142 End of the time bucket (exclusive) in RFC 3339 format.
122143
123 - `results: array of object { cache_creation, cache_read_input_tokens, context_window, 10 more }`
144 format: date-time
124145
146 - `results: array of object`
147
125148 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).
126149
127 - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
150 - `cache_creation: object`
128151
129152 The number of input tokens for cache creation.
130153
from line 199
176199
177200 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`).
178201
179 - `server_tool_use: object { web_search_requests }`
202 - `server_tool_use: object`
180203
181204 Server-side tool usage metrics.
182205
from line 227
204227
205228 Start of the time bucket (inclusive) in RFC 3339 format.
206229
230 format: date-time
231
207232 - `data_refreshed_at: string or null`
208233
209234 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).
210235
236 format: date-time
237
211238 - `has_more: boolean`
212239
213240 Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it.
from line 249
222249
223250### Example
224251
225```http
252```bash
226253curl https://api.anthropic.com/v1/organizations/analytics/usage_report \
227254 -H 'anthropic-version: 2023-06-01' \
228255 -H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
229256```
230257
231#### Response
258#### Response (200)
232259
233260```json
234261{
from line 296
269296
270297## Get Per-User Token Usage
271298
272**get** `/v1/organizations/analytics/user_usage_report`
299**GET** `/v1/organizations/analytics/user_usage_report`
273300
274301Get per-user token usage across a date range.
275302
from line 308
281308organizations on a Claude Enterprise plan. Requires an API key with the
282309`read:analytics` scope.
283310
284### Query Parameters
311### Query parameters
285312
286313- `starting_at: string`
287314
288315 Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
289316
317 format: date-time
318
290319- `bucket_width: optional "1d" or "1h" or "1m"`
291320
292321 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 330
301330
302331 Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
303332
333 maxItems: 100
334
304335 - `"0-200k"`
305336
306337 - `"200k-1M"`
from line 340
309340
310341 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.
311342
343 format: date-time
344
312345- `exclude_deleted_users: optional boolean`
313346
314347 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.
315348
349 default: false
350
316351- `group_by: optional array of "context_window" or "inference_geo" or "model" or 4 more`
317352
318353 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.
319354
355 maxItems: 100
356
320357 - `"context_window"`
321358
322359 - `"inference_geo"`
from line 372
335372
336373 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.
337374
375 maxItems: 100
376
338377 - `"global"`
339378
340379 - `"not_available"`
from line 384
345384
346385 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.
347386
387 default: 20, maximum: 1000, minimum: 1
388
348389- `models: optional array of string`
349390
350391 Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
351392
393 maxItems: 100
394
352395- `order: optional "asc" or "desc"`
353396
354397 Sort direction. Defaults to `desc`.
355398
399 default: desc
400
356401 - `"asc"`
357402
358403 - `"desc"`
from line 406
361406
362407 Metric to rank actors by. Defaults to `total_tokens`.
363408
409 default: total_tokens
410
364411 - `"output_tokens"`
365412
366413 - `"requests"`
from line 424
377424
378425 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.
379426
427 maxItems: 100
428
380429- `rbac_group_ids: optional array of string`
381430
382431 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.
383432
433 maxItems: 100
434
384435- `slack_channel_ids: optional array of string`
385436
386437 Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
387438
439 maxItems: 100
440
388441- `speeds: optional array of "fast" or "standard"`
389442
390443 Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
391444
445 maxItems: 100
446
392447 - `"fast"`
393448
394449 - `"standard"`
from line 452
397452
398453 Filter to specific users by tagged user ID.
399454
455 maxItems: 100
456
400457### Returns
401458
402- `UserUsage object { data, data_refreshed_at, has_more, 2 more }`
459- `UserUsage object`
403460
404 - `data: array of object { actor, cache_creation, cache_read_input_tokens, 14 more }`
461 - `data: array of object`
405462
406463 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.
407464
from line 482
425482
426483 Actor type. Always `"user_actor"`.
427484
428 - `"user_actor"`
429
430485 - `user_id: string`
431486
432487 Tagged user ID.
433488
434 - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
489 - `cache_creation: object`
435490
436491 The number of input tokens for cache creation.
437492
from line 514
459514
460515 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.
461516
517 format: date-time
518
462519 - `inference_geo: "global" or "us" or null`
463520
464521 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 544
487544
488545 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`).
489546
490 - `server_tool_use: object { web_search_requests }`
547 - `server_tool_use: object`
491548
492549 Server-side tool usage metrics.
493550
from line 568
511568
512569 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.
513570
571 format: date-time
572
514573 - `total_tokens: number`
515574
516575 Total token count across all token types. This is the value the default order_by='total_tokens' sorts on.
from line 582
523582
524583 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).
525584
585 format: date-time
586
526587 - `has_more: boolean`
527588
528589 Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it.
from line 598
537598
538599### Example
539600
540```http
601```bash
541602curl https://api.anthropic.com/v1/organizations/analytics/user_usage_report \
542603 -H 'anthropic-version: 2023-06-01' \
543604 -H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
544605```
545606
546#### Response
607#### Response (200)
547608
548609```json
549610{
from line 647
586647}
587648```
588649
589## Domain Types
650## Domain types
590651
591652### Usage Bucket
592653
593- `UsageBucket object { data, data_refreshed_at, has_more, 2 more }`
654- `UsageBucket object`
594655
595 - `data: array of object { ending_at, results, starting_at }`
656 - `data: array of object`
596657
597658 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.
598659
from line 661
600661
601662 End of the time bucket (exclusive) in RFC 3339 format.
602663
603 - `results: array of object { cache_creation, cache_read_input_tokens, context_window, 10 more }`
664 format: date-time
604665
666 - `results: array of object`
667
605668 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).
606669
607 - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
670 - `cache_creation: object`
608671
609672 The number of input tokens for cache creation.
610673
from line 719
656719
657720 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`).
658721
659 - `server_tool_use: object { web_search_requests }`
722 - `server_tool_use: object`
660723
661724 Server-side tool usage metrics.
662725
from line 747
684747
685748 Start of the time bucket (inclusive) in RFC 3339 format.
686749
750 format: date-time
751
687752 - `data_refreshed_at: string or null`
688753
689754 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).
690755
756 format: date-time
757
691758 - `has_more: boolean`
692759
693760 Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it.
from line 769
702769
703770### User Usage
704771
705- `UserUsage object { data, data_refreshed_at, has_more, 2 more }`
772- `UserUsage object`
706773
707 - `data: array of object { actor, cache_creation, cache_read_input_tokens, 14 more }`
774 - `data: array of object`
708775
709776 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.
710777
from line 795
728795
729796 Actor type. Always `"user_actor"`.
730797
731 - `"user_actor"`
732
733798 - `user_id: string`
734799
735800 Tagged user ID.
736801
737 - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
802 - `cache_creation: object`
738803
739804 The number of input tokens for cache creation.
740805
from line 827
762827
763828 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.
764829
830 format: date-time
831
765832 - `inference_geo: "global" or "us" or null`
766833
767834 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 857
790857
791858 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`).
792859
793 - `server_tool_use: object { web_search_requests }`
860 - `server_tool_use: object`
794861
795862 Server-side tool usage metrics.
796863
from line 881
814881
815882 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.
816883
884 format: date-time
885
817886 - `total_tokens: number`
818887
819888 Total token count across all token types. This is the value the default order_by='total_tokens' sorts on.
from line 894
825894 - `data_refreshed_at: string or null`
826895
827896 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).
897
898 format: date-time
828899
829900 - `has_more: boolean`
830901
No line in this hunk matches that.