--- title: Usage Report url: https://platform.claude.com/docs/en/api/go/beta/organization/analytics/usage_report --- # Usage Report ## Get Token Usage Over Time `client.Beta.Organization.Analytics.UsageReport.List(ctx, query) (*PageCursor[BetaAnalyticsUsageReportTimeBucket], error)` **GET** `/v1/organizations/analytics/usage_report` Get token usage over time across a date range. Returns token usage bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, or speed. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. ### Parameters - `query BetaOrganizationAnalyticsUsageReportListParams` - `StartingAt Time` (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. format: date-time - `BucketWidth BetaOrganizationAnalyticsUsageReportListParamsBucketWidth Optional` (query parameter) Time bucket granularity. - `const BetaOrganizationAnalyticsUsageReportListParamsBucketWidthDay BetaOrganizationAnalyticsUsageReportListParamsBucketWidth = "1d"` - `const BetaOrganizationAnalyticsUsageReportListParamsBucketWidthHour BetaOrganizationAnalyticsUsageReportListParamsBucketWidth = "1h"` - `const BetaOrganizationAnalyticsUsageReportListParamsBucketWidthMinute BetaOrganizationAnalyticsUsageReportListParamsBucketWidth = "1m"` - `ClaudeTagCategories []BetaAnalyticsClaudeTagCategory Optional` (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. maxItems: 100 - `const BetaAnalyticsClaudeTagCategoryDm BetaAnalyticsClaudeTagCategory = "dm"` - `const BetaAnalyticsClaudeTagCategoryEngaged BetaAnalyticsClaudeTagCategory = "engaged"` - `const BetaAnalyticsClaudeTagCategoryMonitoring BetaAnalyticsClaudeTagCategory = "monitoring"` - `const BetaAnalyticsClaudeTagCategoryProactive BetaAnalyticsClaudeTagCategory = "proactive"` - `const BetaAnalyticsClaudeTagCategoryScheduled BetaAnalyticsClaudeTagCategory = "scheduled"` - `ClaudeTagUserIDs []string Optional` (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. maxItems: 100 - `ContextWindows []BetaAnalyticsContextWindow Optional` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. maxItems: 100 - `const BetaAnalyticsContextWindowFrom0To200k BetaAnalyticsContextWindow = "0-200k"` - `const BetaAnalyticsContextWindowFrom200kTo1M BetaAnalyticsContextWindow = "200k-1M"` - `EndingAt param.Opt[Time] Optional` (query parameter) 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 - `GroupBy []string Optional` (query parameter) 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. maxItems: 100 - `const BetaOrganizationAnalyticsUsageReportListParamsGroupByClaudeTagCategory BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "claude_tag_category"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupByClaudeTagUserID BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "claude_tag_user_id"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupByContextWindow BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "context_window"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupByInferenceGeo BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "inference_geo"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupByModel BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "model"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupByProduct BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "product"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupByRBACGroupID BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "rbac_group_id"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupBySlackChannelID BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "slack_channel_id"` - `const BetaOrganizationAnalyticsUsageReportListParamsGroupBySpeed BetaOrganizationAnalyticsUsageReportListParamsGroupBy = "speed"` - `InferenceGeos []BetaAnalyticsInferenceGeoFilter Optional` (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. maxItems: 100 - `const BetaAnalyticsInferenceGeoFilterGlobal BetaAnalyticsInferenceGeoFilter = "global"` - `const BetaAnalyticsInferenceGeoFilterNotAvailable BetaAnalyticsInferenceGeoFilter = "not_available"` - `const BetaAnalyticsInferenceGeoFilterUs BetaAnalyticsInferenceGeoFilter = "us"` - `Limit param.Opt[int64] Optional` (query parameter) 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). minimum: 1 - `Models []string Optional` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. maxItems: 100 - `Page param.Opt[string] Optional` (query parameter) Opaque cursor from a previous response's `next_page` field. - `Products []BetaAnalyticsProductFilter Optional` (query parameter) Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. maxItems: 100 - `const BetaAnalyticsProductFilterChat BetaAnalyticsProductFilter = "chat"` - `const BetaAnalyticsProductFilterChatCoworkUnified BetaAnalyticsProductFilter = "chat_cowork_unified"` - `const BetaAnalyticsProductFilterClaudeTag BetaAnalyticsProductFilter = "claude-tag"` - `const BetaAnalyticsProductFilterClaudeCode BetaAnalyticsProductFilter = "claude_code"` - `const BetaAnalyticsProductFilterClaudeDesign BetaAnalyticsProductFilter = "claude_design"` - `const BetaAnalyticsProductFilterClaudeInChrome BetaAnalyticsProductFilter = "claude_in_chrome"` - `const BetaAnalyticsProductFilterCowork BetaAnalyticsProductFilter = "cowork"` - `const BetaAnalyticsProductFilterOfficeAgent BetaAnalyticsProductFilter = "office_agent"` - `RBACGroupIDs []string Optional` (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. maxItems: 100 - `SlackChannelIDs []string Optional` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. maxItems: 100 - `Speeds []string Optional` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. maxItems: 100 - `const BetaOrganizationAnalyticsUsageReportListParamsSpeedFast BetaOrganizationAnalyticsUsageReportListParamsSpeed = "fast"` - `const BetaOrganizationAnalyticsUsageReportListParamsSpeedStandard BetaOrganizationAnalyticsUsageReportListParamsSpeed = "standard"` - `UserIDs []string Optional` (query parameter) Filter to specific users by tagged user ID. maxItems: 100 ### Returns - `type BetaAnalyticsUsageReportTimeBucket` - `EndingAt Time` End of the time bucket (exclusive) in RFC 3339 format. format: date-time - `Results []BetaAnalyticsUsageBucketedResult` 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). - `CacheCreation BetaCacheCreation` The number of input tokens for cache creation. - `Ephemeral1hInputTokens int64` The number of input tokens used to create the 1 hour cache entry. default: 0, minimum: 0 - `Ephemeral5mInputTokens int64` The number of input tokens used to create the 5 minute cache entry. default: 0, minimum: 0 - `CacheReadInputTokens int64` The number of input tokens read from the cache. - `ClaudeTagCategory BetaAnalyticsClaudeTagCategory` 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. - `const BetaAnalyticsClaudeTagCategoryDm BetaAnalyticsClaudeTagCategory = "dm"` - `const BetaAnalyticsClaudeTagCategoryEngaged BetaAnalyticsClaudeTagCategory = "engaged"` - `const BetaAnalyticsClaudeTagCategoryMonitoring BetaAnalyticsClaudeTagCategory = "monitoring"` - `const BetaAnalyticsClaudeTagCategoryProactive BetaAnalyticsClaudeTagCategory = "proactive"` - `const BetaAnalyticsClaudeTagCategoryScheduled BetaAnalyticsClaudeTagCategory = "scheduled"` - `ClaudeTagUserID string` 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. - `ContextWindow BetaAnalyticsContextWindow` 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. - `const BetaAnalyticsContextWindowFrom0To200k BetaAnalyticsContextWindow = "0-200k"` - `const BetaAnalyticsContextWindowFrom200kTo1M BetaAnalyticsContextWindow = "200k-1M"` - `InferenceGeo BetaAnalyticsUsageBucketedResultInferenceGeo` 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). - `const BetaAnalyticsUsageBucketedResultInferenceGeoGlobal BetaAnalyticsUsageBucketedResultInferenceGeo = "global"` - `const BetaAnalyticsUsageBucketedResultInferenceGeoUs BetaAnalyticsUsageBucketedResultInferenceGeo = "us"` - `Model string` 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. - `OutputTokens int64` The number of output tokens generated. - `Product string` 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 on deployments that offer Chat and Cowork unified. Some unattributed usage is reported as "other". - `RBACGroupID string` 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[]`. - `Requests int64` 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`). - `ServerToolUse BetaAnalyticsServerToolUse` Server-side tool usage metrics. - `WebSearchRequests int64` The number of web search requests made. - `SlackChannelID string` 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). - `Speed BetaAnalyticsUsageBucketedResultSpeed` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `const BetaAnalyticsUsageBucketedResultSpeedFast BetaAnalyticsUsageBucketedResultSpeed = "fast"` - `const BetaAnalyticsUsageBucketedResultSpeedStandard BetaAnalyticsUsageBucketedResultSpeed = "standard"` - `UncachedInputTokens int64` The number of uncached input tokens processed. - `StartingAt Time` Start of the time bucket (inclusive) in RFC 3339 format. format: date-time ### Example ```go package main import ( "context" "fmt" "time" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/option" ) func main() { client := anthropic.NewClient( option.WithAPIKey("my-anthropic-api-key"), ) page, err := client.Beta.Organization.Analytics.UsageReport.List(context.TODO(), anthropic.BetaOrganizationAnalyticsUsageReportListParams{ StartingAt: time.Now(), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response (200) ```json { "data": [ { "ending_at": "2019-12-27T18:11:19.117Z", "results": [ { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "inference_geo": "global", "model": "claude-opus-5-5", "output_tokens": 0, "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 0, "server_tool_use": { "web_search_requests": 10 }, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "uncached_input_tokens": 0 } ], "starting_at": "2019-12-27T18:11:19.117Z" } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" } ```