# Get Per-User Token Usage ## Query parameters ## Returns ## Example ### Response (200)
The whole hunk
421 lines, new page
/
lines
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Get Per-User Token Usage
url: https://platform.claude.com/docs/en/api/beta/organization/analytics/usage/list_by_user
---
# Get Per-User Token Usage
**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
see which users consume the most tokens. Only usage attributable to a
seat user is included; for organization-wide totals including direct
API-key and automation traffic, use the bucketed
`/v1/organizations/analytics/usage_report` endpoint. Available to
organizations on a Claude Enterprise plan. Requires an API key with the
`read:analytics` scope.
## 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.
- `"1d"`
- `"1h"`
- `"1m"`
- `claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more`
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems: 100
- `"dm"`
- `"engaged"`
- `"monitoring"`
- `"proactive"`
- `"scheduled"`
- `claude_tag_user_ids: optional array of string`
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems: 100
- `context_windows: optional array of "0-200k" or "200k-1M"`
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems: 100
- `"0-200k"`
- `"200k-1M"`
- `ending_at: optional string`
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 "claude_tag_category" or "claude_tag_user_id" or "context_window" or 6 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
- `"claude_tag_category"`
- `"claude_tag_user_id"`
- `"context_window"`
- `"inference_geo"`
- `"model"`
- `"product"`
- `"rbac_group_id"`
- `"slack_channel_id"`
- `"speed"`
- `inference_geos: optional array of "global" or "not_available" or "us"`
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"`
- `"us"`
- `limit: optional number`
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"`
- `order_by: optional "output_tokens" or "requests" or "total_tokens" or "uncached_input_tokens"`
Metric to rank actors by. Defaults to `total_tokens`.
default: total_tokens
- `"output_tokens"`
- `"requests"`
- `"total_tokens"`
- `"uncached_input_tokens"`
- `page: optional string`
Opaque cursor from a previous response's `next_page` field.
- `products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more`
Product surfaces to include. Defaults to all products.
maxItems: 100
- `"chat"`
- `"claude-tag"`
- `"claude_code"`
- `"claude_design"`
- `"claude_in_chrome"`
- `"cowork"`
- `"office_agent"`
- `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"`
- `user_ids: optional array of string`
Filter to specific users by tagged user ID.
maxItems: 100
## Returns
- `BetaUserUsage 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: BetaAnalyticsUserActor`
The user this row's usage or cost is attributed to. Always a `user_actor`.
- `type: "user_actor"`
Actor type. Always `"user_actor"`.
- `deleted: boolean`
True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation.
- `email: string or null`
The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`).
- `name: string or null`
The user's full name. Null when the user has not set a name. Returns `"Deleted User"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `"Claude Security"` for usage by Anthropic's security-patching service) or null.
- `user_id: string`
Tagged user ID.
- `cache_creation: BetaCacheCreation`
The number of input tokens for cache creation.
- `ephemeral_1h_input_tokens: number`
The number of input tokens used to create the 1 hour cache entry.
default: 0, minimum: 0
- `ephemeral_5m_input_tokens: number`
The number of input tokens used to create the 5 minute cache entry.
default: 0, minimum: 0
- `cache_read_input_tokens: number`
The number of input tokens read from the cache.
- `claude_tag_category: "dm" or "engaged" or "monitoring" or 2 more or null`
Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time.
- `"dm"`
- `"engaged"`
- `"monitoring"`
- `"proactive"`
- `"scheduled"`
- `claude_tag_user_id: string or null`
Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter.
- `context_window: "0-200k" or "200k-1M" or null`
Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution.
- `"0-200k"`
- `"200k-1M"`
- `ending_at: string or null`
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).
- `"global"`
- `"us"`
- `model: string or null`
Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution.
Cut at 300 lines. The page has the rest.