## Get Messages Usage Report ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The whole hunk
297 lines, first recorded
/
lines
The first capture of this source. The page was already there, and this is what it said.
---
title: Get Messages Usage Report
url: https://platform.claude.com/docs/en/api/admin/usage_report/retrieve_messages
---
## 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 "1h" or "1m"`
Time granularity of the response data.
- `"1d"`
- `"1h"`
- `"1m"`
- `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 "account_id" or "api_key_id" or "context_window" or 6 more`
Group by any subset of the available options. Grouping by `speed` requires the `fast-mode-2026-02-01` beta header.
- `"account_id"`
- `"api_key_id"`
- `"context_window"`
- `"inference_geo"`
- `"model"`
- `"service_account_id"`
- `"service_tier"`
- `"speed"`
- `"workspace_id"`
- `inference_geos: optional array of "global" or "not_available" or "us"`
Restrict usage returned to the specified inference geo(s). Use `not_available` for models that do not support specifying `inference_geo`.
- `"global"`
- `"not_available"`
- `"us"`
- `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 "batch" or "flex" or "flex_discount" or 3 more`
Restrict usage returned to the specified service tier(s).
- `"batch"`
- `"flex"`
- `"flex_discount"`
- `"priority"`
- `"priority_on_demand"`
- `"standard"`
- `speeds: optional array of "fast" or "standard"`
Restrict usage returned to the specified speed(s) (Claude Code research preview).
Requires the `fast-mode-2026-02-01` beta header.
- `"fast"`
- `"standard"`
- `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 }`
List of time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no usage (their `results` list is empty). A page holds at most `limit` buckets.
- `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 or null`
ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests.
- `api_key_id: string or null`
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" or null`
Context window used. `null` if not grouping by context window.
- `"0-200k"`
- `"200k-1M"`
- `inference_geo: "global" or "not_available" or "us" or null`
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.
- `"global"`
- `"not_available"`
- `"us"`
- `model: string or null`
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 or null`
ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests.
- `service_tier: "batch" or "flex" or "flex_discount" or 3 more or null`
Service tier used. `null` if not grouping by service tier.
- `"batch"`
- `"flex"`
- `"flex_discount"`
- `"priority"`
- `"priority_on_demand"`
- `"standard"`
- `uncached_input_tokens: number`
The number of uncached input tokens processed.
- `workspace_id: string or null`
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 or null`
Opaque cursor for the next page, or `null` when `has_more` is false. Pass it as the `page` parameter in the next request.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
#### 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": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```