Usage changedapi/beta/organization/analytics/usage

A whole new page. There's nothing to diff it against, so here is what it says.

---
title: Usage
url: https://platform.claude.com/docs/en/api/beta/organization/analytics/usage
---

# Usage

## Get Token Usage By Dimension

**GET** `/v1/organizations/analytics/usage`

Get token usage across a date range, broken out by dimension.

Returns one row per combination of the requested `group_by[]`
dimensions (and time bucket, when `time_bucket_width` is set) that has
usage in the range, ranked by the `order_by` metric or ordered by time
bucket; every combination is returned across pages. With no `group_by[]`
and no `time_bucket_width`, a single row aggregates the whole range.
Includes all usage, whether or not it is attributable to a seat user.
Requires an API key with the `read:analytics` scope, or an Admin API key.

### 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

- `actor_ids: optional array of string`

  Filter to usage attributed to specific identities, by tagged ID: a `user_...`, `svac_...` (service account), or `apikey_...` ID. An `apikey_` entry matches only usage attributed to the key itself, not usage on that key attributed to a user or service account (use `api_key_ids[]` for every request a key authenticated). Federated identities have no tagged ID; select them with `actor_types[]`. Use `group_by[]=actor` to break out per-identity values.

  maxItems: 100

- `actor_types: optional array of BetaAnalyticsActorType`

  Filter to usage attributed to specific kinds of identity. Use `group_by[]=actor_type` to break out per-kind values.

  maxItems: 100

  - `"api_actor"`

  - `"federated_actor"`

  - `"service_account_actor"`

  - `"user_actor"`

- `agent_ids: optional array of string`

  Filter to usage incurred by sessions of specific Claude Managed Agents agents. Use `group_by[]=agent_id` to break out per-agent values. Claude Developer Platform organizations only.

  maxItems: 100

- `api_key_ids: optional array of string`

  Filter to usage authenticated by specific API keys, by tagged API key ID (`apikey_...`), whichever identity the usage is attributed to. Include an empty entry (`api_key_ids[]=`) to also match usage that no API key authenticated. Use `group_by[]=api_key_id` to break out per-key values; usage without a key has a null `api_key_id`. Claude Developer Platform organizations only.

  maxItems: 100

- `claude_tag_categories: optional array of BetaAnalyticsClaudeTagCategory`

  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 BetaAnalyticsContextWindow`

  Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.

  maxItems: 100

  - `"0-200k"`

  - `"200k-1M"`

- `deployment_ids: optional array of string`

  Filter to usage incurred by Claude Managed Agents sessions that specific deployments started. Use `group_by[]=deployment_id` to break out per-deployment values. Claude Developer Platform organizations only.

  maxItems: 100

- `ending_at: optional string`

  End of range, exclusive. Required when `time_bucket_width` is set. Without `time_bucket_width`, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.

  format: date-time

- `environment_ids: optional array of string`

  Filter to usage incurred by Claude Managed Agents sessions that ran in specific environments. Use `group_by[]=environment_id` to break out per-environment values. Claude Developer Platform organizations only.

  maxItems: 100

- `exclude_deleted_users: optional boolean`

  If true, omit rows whose `actor` is a `user_actor` with `deleted: true`. Requires `group_by[]=actor`. Rows for other actor types, and rows whose `actor` is null, are always kept. 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 BetaAnalyticsUsageGroupBy`

  Dimensions to break usage out by (at most 5): one row per combination of their values with usage in the range (and per time bucket, when `time_bucket_width` is set), every combination returned across pages rather than a capped top set. When omitted, a single row aggregates the whole range.

  maxItems: 100

  - `"actor"`

  - `"actor_type"`

  - `"agent_id"`

  - `"api_key_id"`

  - `"claude_tag_category"`

  - `"claude_tag_user_id"`

  - `"context_window"`

  - `"deployment_id"`

  - `"environment_id"`

  - `"inference_geo"`

  - `"model"`

  - `"product"`

  - `"rbac_group_id"`

  - `"service_tier"`

  - `"session_id"`

  - `"slack_channel_id"`

  - `"speed"`

  - `"user_profile_id"`

  - `"workspace_id"`

- `inference_geos: optional array of BetaAnalyticsInferenceGeoFilter`

  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). `cost_type`/`token_type` fan-out rows (cost endpoint only) do not count toward this limit, so `data` can exceed it.

  default: 20, minimum: 1, maximum: 1000

- `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 BetaAnalyticsUsageCostSortOrder`

  Sort direction of the `order_by` metric, or of the time buckets when `order_by` is `time` and `time_bucket_width` is set. Defaults to `desc`.

  - `"asc"`

  - `"desc"`

- `order_by: optional BetaAnalyticsUsageOrderBy`

  Row order. A metric ranks rows by that metric in the `order` direction. `time` orders rows by time bucket in the `order` direction (newest first by default) and, within a bucket, by `total_tokens`, highest first. `time` takes effect only with `time_bucket_width`; without it, `time` is the same as `total_tokens`. Defaults to `total_tokens`.

  - `"output_tokens"`

  - `"requests"`

  - `"time"`

  - `"total_tokens"`

  - `"uncached_input_tokens"`

- `page: optional string`

  Opaque cursor from a previous response's `next_page` field.

- `products: optional array of BetaAnalyticsUsageCostProductFilter`

  Product surfaces to include. Defaults to all products.

  maxItems: 100

  - `"chat"`

  - `"chat_cowork_unified"`

  - `"claude_code"`

  - `"claude_console"`

  - `"claude_design"`

  - `"claude_in_chrome"`

  - `"claude_tag"`

  - `"cowork"`

  - `"managed_agents_api"`

  - `"message_batches_api"`

  - `"messages_api"`

  - `"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

- `service_tiers: optional array of BetaAnalyticsServiceTier`

  Filter to specific service tiers. Use `group_by[]=service_tier` to break out per-tier values. Claude Developer Platform organizations only; matches nothing for a Claude Enterprise organization.

  maxItems: 100

  - `"batch"`

  - `"flex"`

  - `"flex_discount"`

  - `"priority"`

  - `"priority_on_demand"`

  - `"standard"`

- `session_ids: optional array of string`

  Filter to usage incurred by specific Claude Managed Agents sessions, by tagged session ID (`sesn_...`). Use `group_by[]=session_id` to break out per-session values. Claude Developer Platform organizations only.

  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 BetaAnalyticsSpeed`

  Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.

  maxItems: 100

  - `"fast"`

  - `"standard"`

- `time_bucket_width: optional BetaAnalyticsTimeBucketWidth`

  Time-bucket granularity. When set, rows are returned per time bucket (one per bucket and dimension combination with usage) and each row's `starting_at` and `ending_at` are that bucket's bounds; the time bucket counts toward `limit`. `ending_at` is required when `time_bucket_width` is set, and with `time_bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the requested range with `starting_at` and `ending_at` each rounded down to the hour.

  - `"1d"`

  - `"1h"`

  - `"1m"`

- `user_profile_ids: optional array of string`

  Filter to usage attributed to specific user profiles, by tagged user profile ID (`uprof_...`). Use `group_by[]=user_profile_id` to break out per-profile values. Claude Developer Platform organizations only.

Cut at 300 lines. The page has the rest.

No line in this hunk matches that.