## Get Messages Usage Report **get** `/v1/organizations/usage_report/messages` Get Messages Usage Report ### Query Parameters - `starting_at: string` Time buckets that start on or after this RFC 3339 timestamp will be returned. Each time bucket will be snapped to the start of the minute/hour/day in UTC. - `account_ids: optional array of string` Restrict usage returned to the specified user account ID(s). - `api_key_ids: optional array of string` Restrict usage returned to the specified API key ID(s). - `bucket_width: optional "1d" or "1m" or "1h"` Time granularity of the response data. - `"1d"` - `"1m"` - `"1h"` - `context_window: optional array of "0-200k" or "200k-1M"` Restrict usage returned to the specified context window(s). - `"0-200k"` - `"200k-1M"` - `ending_at: optional string` Time buckets that end before this RFC 3339 timestamp will be returned. - `group_by: optional array of "api_key_id" or "workspace_id" or "model" or 6 more` Group by any subset of the available options. Grouping by `speed` requires the `fast-mode-2026-02-01` beta header. - `"api_key_id"` - `"workspace_id"` - `"model"` - `"service_tier"` - `"context_window"` - `"inference_geo"` - `"speed"` - `"account_id"` - `"service_account_id"` - `inference_geos: optional array of "global" or "us" or "not_available"` Restrict usage returned to the specified inference geo(s). Use `not_available` for models that do not support specifying `inference_geo`. - `"global"` - `"us"` - `"not_available"` - `limit: optional number` Maximum number of time buckets to return in the response. The default and max limits depend on `bucket_width`: • `"1d"`: Default of 7 days, maximum of 31 days • `"1h"`: Default of 24 hours, maximum of 168 hours • `"1m"`: Default of 60 minutes, maximum of 1440 minutes - `models: optional array of string` Restrict usage returned to the specified model(s). - `page: optional string` Optionally set to the `next_page` token from the previous response. - `service_account_ids: optional array of string` Restrict usage returned to the specified service account ID(s). - `service_tiers: optional array of "standard" or "batch" or "priority" or 3 more` Restrict usage returned to the specified service tier(s). - `"standard"` - `"batch"` - `"priority"` - `"priority_on_demand"` - `"flex"` - `"flex_discount"` - `speeds: optional array of "standard" or "fast"` Restrict usage returned to the specified speed(s) (Claude Code research preview). Requires the `fast-mode-2026-02-01` beta header. - `"standard"` - `"fast"` - `workspace_ids: optional array of string` Restrict usage returned to the specified workspace ID(s). ### Header Parameters - `"anthropic-beta": optional array of string` Optional header to specify the beta version(s) you want to use. To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta. ### Returns - `MessagesUsageReport object { data, has_more, next_page }` - `data: array of object { ending_at, results, starting_at }` - `ending_at: string` End of the time bucket (exclusive) in RFC 3339 format. - `results: array of object { account_id, api_key_id, cache_creation, 10 more }` List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified. - `account_id: string` ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests. - `api_key_id: string` ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console. - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` 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. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_read_input_tokens: number` The number of input tokens read from the cache. - `context_window: "0-200k" or "200k-1M"` Context window used. `null` if not grouping by context window. - `"0-200k"` - `"200k-1M"` - `inference_geo: string` Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`. For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo. - `model: string` Model used. `null` if not grouping by model. - `output_tokens: number` The number of output tokens generated. - `server_tool_use: object { web_search_requests }` Server-side tool usage metrics. - `web_search_requests: number` The number of web search requests made. - `service_account_id: string` ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests. - `service_tier: "standard" or "batch" or "priority" or 3 more` Service tier used. `null` if not grouping by service tier. - `"standard"` - `"batch"` - `"priority"` - `"priority_on_demand"` - `"flex"` - `"flex_discount"` - `uncached_input_tokens: number` The number of uncached input tokens processed. - `workspace_id: string` ID of the Workspace used. `null` if not grouping by workspace or for the default workspace. - `starting_at: string` Start of the time bucket (inclusive) in RFC 3339 format. - `has_more: boolean` Indicates if there are more results. - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. ### Example ```http curl https://api.anthropic.com/v1/organizations/usage_report/messages \ -H 'anthropic-version: 2023-06-01' \ -H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" ``` #### Response ```json { "data": [ { "ending_at": "2025-08-02T00:00:00Z", "results": [ { "account_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "cache_creation": { "ephemeral_1h_input_tokens": 1000, "ephemeral_5m_input_tokens": 500 }, "cache_read_input_tokens": 200, "context_window": "0-200k", "inference_geo": "global", "model": "claude-opus-4-6", "output_tokens": 500, "server_tool_use": { "web_search_requests": 10 }, "service_account_id": "svac_01Hk3R9TWxq7CfQak00OiVw4", "service_tier": "standard", "uncached_input_tokens": 1500, "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ], "starting_at": "2025-08-01T00:00:00Z" } ], "has_more": true, "next_page": "2019-12-27T18:11:19.117Z" } ```