--- title: Usage url: https://platform.claude.com/docs/en/api/php/beta/organization/analytics/usage --- # Usage ## Get Token Usage By Dimension `$client->beta->organization->analytics->usage->list(\Datetime startingAt, ?list actorIDs, ?list actorTypes, ?list agentIDs, ?list apiKeyIDs, ?list claudeTagCategories, ?list claudeTagUserIDs, ?list contextWindows, ?list deploymentIDs, ?\Datetime endingAt, ?list environmentIDs, ?bool excludeDeletedUsers, ?list groupBy, ?list inferenceGeos, ?int limit, ?list models, ?AnalyticsUsageCostSortOrder order, ?BetaAnalyticsUsageOrderBy orderBy, ?string page, ?list products, ?list rbacGroupIDs, ?list serviceTiers, ?list sessionIDs, ?list slackChannelIDs, ?list speeds, ?AnalyticsTimeBucketWidth timeBucketWidth, ?list userProfileIDs, ?list workspaceIDs, ?list betas): ReportPageCursor` **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. ### Parameters - `startingAt: \Datetime` (query parameter) Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z. - `actorIDs?: optional list` (query parameter) 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. - `actorTypes?: optional list` (query parameter) Filter to usage attributed to specific kinds of identity. Use `group_by[]=actor_type` to break out per-kind values. - `agentIDs?: optional list` (query parameter) 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. - `apiKeyIDs?: optional list` (query parameter) 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. - `claudeTagCategories?: optional list` (query parameter) 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. - `claudeTagUserIDs?: optional list` (query parameter) 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. - `contextWindows?: optional list` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. - `deploymentIDs?: optional list` (query parameter) 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. - `endingAt?: optional \Datetime` (query parameter) 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. - `environmentIDs?: optional list` (query parameter) 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. - `excludeDeletedUsers?: optional bool` (query parameter) 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 - `groupBy?: optional list` (query parameter) 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. - `inferenceGeos?: optional list` (query parameter) 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. - `limit?: optional int` (query parameter) 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 - `models?: optional list` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. - `order?: optional AnalyticsUsageCostSortOrder` (query parameter) 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`. - `orderBy?: optional BetaAnalyticsUsageOrderBy` (query parameter) 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`. - `page?: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `products?: optional list` (query parameter) Product surfaces to include. Defaults to all products. - `rbacGroupIDs?: optional list` (query parameter) 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. - `serviceTiers?: optional list` (query parameter) 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. - `sessionIDs?: optional list` (query parameter) 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. - `slackChannelIDs?: optional list` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. - `speeds?: optional list` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. - `timeBucketWidth?: optional AnalyticsTimeBucketWidth` (query parameter) 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. - `userProfileIDs?: optional list` (query parameter) 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. - `workspaceIDs?: optional list` (query parameter) Filter to usage in specific workspaces, by tagged workspace ID (`wrkspc_...`). Use `group_by[]=workspace_id` to break out per-workspace values. Claude Developer Platform organizations only; matches nothing for a Claude Enterprise organization. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `analytics-usage-cost-2026-08-24` in this header. ### Returns - `class BetaAnalyticsUsageItem` - `\Datetime endingAt` End of the period this row covers (exclusive), as an RFC 3339 UTC timestamp: the end of the row's time bucket when a time-bucket width is set; otherwise the requested `ending_at` (or, when omitted, the earlier of now and `starting_at` plus 31 days) rounded down to the hour, because without a time bucket the report covers whole hours. - `BetaAnalyticsUsageGroup group` The dimension values this row's usage is broken out by. - `\Datetime startingAt` Start of the period this row covers (inclusive), as an RFC 3339 UTC timestamp: the start of the row's time bucket when a time-bucket width is set, otherwise the requested `starting_at` rounded down to the hour. - `BetaAnalyticsUsageMetrics usage` Token usage for this row. ### Example ```php beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), actorIDs: ['user_01WxYzAbCdEfGhJkMnPqRsTu'], actorTypes: [AnalyticsActorType::SERVICE_ACCOUNT_ACTOR], agentIDs: ['agent_01VHd3EAGJ6PLkP9LM7DDu3f'], apiKeyIDs: ['apikey_01Rj2N8SVvo6BePZj99NhmiT'], claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED], claudeTagUserIDs: ['U0123ABCDEF'], contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K], deploymentIDs: ['depl_01JFC6ihzZHtAuyHsaENdJhY'], endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), environmentIDs: ['env_017oTjuGedHtjhJauVC5xGJD'], excludeDeletedUsers: true, groupBy: [BetaAnalyticsUsageGroupBy::ACTOR], inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL], limit: 1, models: ['string'], order: AnalyticsUsageCostSortOrder::ASC, orderBy: BetaAnalyticsUsageOrderBy::OUTPUT_TOKENS, page: 'page', products: [AnalyticsUsageCostProductFilter::CHAT], rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'], serviceTiers: [AnalyticsServiceTier::BATCH], sessionIDs: ['sesn_0187kPDyNCwibNNvfaPEApCJ'], slackChannelIDs: ['C0123ABCDEF'], speeds: [AnalyticsSpeed::FAST], timeBucketWidth: AnalyticsTimeBucketWidth::DAY, userProfileIDs: ['uprof_01M33NeYUQK2WV9PpYcsPHLi'], workspaceIDs: ['wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], ); var_dump($page); ``` #### Response (200) ```json { "data": [ { "ending_at": "2026-10-01T00:00:00Z", "group": { "actor": { "deleted": false, "email_address": "user@emaildomain.com", "name": "Jane Doe", "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" }, "actor_type": "user_actor", "agent_id": "agent_01VHd3EAGJ6PLkP9LM7DDu3f", "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "deployment_id": "depl_01JFC6ihzZHtAuyHsaENdJhY", "environment_id": "env_017oTjuGedHtjhJauVC5xGJD", "inference_geo": "global", "model": "claude-opus-5-5", "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "service_tier": "standard", "session_id": "sesn_0187kPDyNCwibNNvfaPEApCJ", "slack_channel_id": "C0123ABCDEF", "speed": "fast", "user_profile_id": "uprof_01M33NeYUQK2WV9PpYcsPHLi", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "starting_at": "2026-09-01T00:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 3200000, "output_tokens": 891000, "requests": 128, "server_tool_use": { "web_search_requests": 10 }, "total_tokens": 5375500, "uncached_input_tokens": 1284500 } } ], "data_refreshed_at": "2026-10-01T04:02:11Z", "has_more": true, "next_page": "next_page" } ``` ## Domain types ### Beta Analytics Usage Group - `class BetaAnalyticsUsageGroup` - `?AnalyticsActor actor` The identity the usage is attributed to: the user if one is attributed, else the service account, else the federated (cloud-platform) identity, else the API key. Populated only when `actor` is in `group_by[]`; null for usage with no attributable identity, and for users' and federated identities' usage when the reader is a member who can see only some workspaces. Distinct identities the server cannot render also read null, each as its own row. - `?AnalyticsActorType actorType` Kind of identity the usage is attributed to; matches `actor.type` when `actor` is set. Populated only when `actor_type` is in `group_by[]`. - `?string agentID` Claude Managed Agents agent whose session incurred the usage. Populated only when `agent_id` is in `group_by[]`; null for usage outside a managed session. - `?string apiKeyID` API key that authenticated the requests, as a tagged API key ID, whichever identity `actor` resolves to. Populated only when `api_key_id` is in `group_by[]`; null for usage not authenticated by an API key. - `?AnalyticsClaudeTagCategory claudeTagCategory` 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. - `?string claudeTagUserID` 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. - `?AnalyticsContextWindow contextWindow` 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. - `?string deploymentID` Deployment that started the Claude Managed Agents session. Populated only when `deployment_id` is in `group_by[]`; null for usage outside a managed session and for sessions no deployment started. - `?string environmentID` Claude Managed Agents environment the session ran in. Populated only when `environment_id` is in `group_by[]`; null for usage outside a managed session. - `?AnalyticsUsageCostInferenceGeo inferenceGeo` 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). - `?string model` Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5-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. - `?string product` Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, `claude_tag`, and `chat_cowork_unified`. `claude_tag` is Claude Tag, the Claude product in Slack. `chat_cowork_unified` is Chat and Cowork unified, Cowork's features inside claude.ai chat: chat and Cowork usage by a member who has it turned on is reported under this value instead of `chat` or `cowork`. It is accepted as a filter only where Chat and Cowork unified is available. Some unattributed usage is reported as "other". - `?string rbacGroupID` RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`. - `?AnalyticsServiceTier serviceTier` Service tier the usage was served at. Populated only when `service_tier` is in `group_by[]`; null for usage with no service tier (for example, code execution) and for Claude Enterprise usage. - `?string sessionID` Claude Managed Agents session that incurred the usage. Populated only when `session_id` is in `group_by[]`; null for usage outside a managed session. - `?string slackChannelID` Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled). - `?AnalyticsSpeed speed` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `?string userProfileID` User profile the usage was attributed to, as a tagged `uprof_` ID. Populated only when `user_profile_id` is in `group_by[]`; null for usage that named no profile and for Claude Enterprise usage. - `?string workspaceID` Workspace the usage occurred in, as a tagged workspace ID, including the organization's default workspace. Populated only when `workspace_id` is in `group_by[]`; null for Claude Enterprise usage. ### Beta Analytics Usage Group By - `enum BetaAnalyticsUsageGroupBy` - `"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"` ### Beta Analytics Usage Item - `class BetaAnalyticsUsageItem` - `\Datetime endingAt` End of the period this row covers (exclusive), as an RFC 3339 UTC timestamp: the end of the row's time bucket when a time-bucket width is set; otherwise the requested `ending_at` (or, when omitted, the earlier of now and `starting_at` plus 31 days) rounded down to the hour, because without a time bucket the report covers whole hours. - `BetaAnalyticsUsageGroup group` The dimension values this row's usage is broken out by. - `\Datetime startingAt` Start of the period this row covers (inclusive), as an RFC 3339 UTC timestamp: the start of the row's time bucket when a time-bucket width is set, otherwise the requested `starting_at` rounded down to the hour. - `BetaAnalyticsUsageMetrics usage` Token usage for this row. ### Beta Analytics Usage Metrics - `class BetaAnalyticsUsageMetrics` - `BetaCacheCreation cacheCreation` The number of input tokens for cache creation. - `int cacheReadInputTokens` The number of input tokens read from the cache. - `int outputTokens` The number of output tokens generated. - `?int requests` 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`). - `AnalyticsServerToolUse serverToolUse` Server-side tool usage metrics. - `int totalTokens` Total token count across all token types. This is the value the default `order_by` (`total_tokens`) sorts on. - `int uncachedInputTokens` The number of uncached input tokens processed. ### Beta Analytics Usage Order By - `enum BetaAnalyticsUsageOrderBy` - `"output_tokens"` - `"requests"` - `"time"` - `"total_tokens"` - `"uncached_input_tokens"`