Sign in

Get Messages Usage Report

get/v1/organizations/usage_report/messages?beta=true

Query parameters

limitinteger

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

Example:7

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

pagestring nullable

Optionally set to the next_page token from the previous response.

Example:page_MjAyNS0wNS0xNFQwMDowMDowMFo=

Optionally set to the next_page token from the previous response.

starting_atstring date-time required

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.

Example:2024-10-30T23:58:27.427722Z

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.

ending_atstring date-time nullable

Time buckets that end before this RFC 3339 timestamp will be returned.

Example:2024-10-30T23:58:27.427722Z

Time buckets that end before this RFC 3339 timestamp will be returned.

api_key_ids[]string[] nullable

Restrict usage returned to the specified API key ID(s).

Restrict usage returned to the specified API key ID(s).

workspace_ids[]string[] nullable

Restrict usage returned to the specified workspace ID(s).

Restrict usage returned to the specified workspace ID(s).

account_ids[]string[] nullable

Restrict usage returned to the specified user account ID(s).

Restrict usage returned to the specified user account ID(s).

service_account_ids[]string[] nullable

Restrict usage returned to the specified service account ID(s).

Restrict usage returned to the specified service account ID(s).

models[]string[] nullable

Restrict usage returned to the specified model(s).

Restrict usage returned to the specified model(s).

service_tiers[]BetaUsageReportServiceTier[] nullable

Restrict usage returned to the specified service tier(s).

Restrict usage returned to the specified service tier(s).

context_window[]BetaMessagesUsageReportContextWindow[] nullable

Restrict usage returned to the specified context window(s).

Restrict usage returned to the specified context window(s).

inference_geos[]BetaInferenceGeoFilter[] nullable

Restrict usage returned to the specified inference geo(s). Use not_available for models that do not support specifying inference_geo.

Restrict usage returned to the specified inference geo(s). Use not_available for models that do not support specifying inference_geo.

speeds[]BetaSpeed[] nullable

Restrict usage returned to the specified speed(s) (Claude Code research preview). Requires the fast-mode-2026-02-01 beta header.

Restrict usage returned to the specified speed(s) (Claude Code research preview). Requires the fast-mode-2026-02-01 beta header.

group_by[]BetaMessagesUsageReportGroupBy[] nullable

Group by any subset of the available options. Grouping by speed requires the fast-mode-2026-02-01 beta header.

Group by any subset of the available options. Grouping by speed requires the fast-mode-2026-02-01 beta header.

bucket_width'1d' | '1h' | '1m'

Time granularity of the response data.

Headers

anthropic-betastring

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.

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.

x-api-keystring

Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

anthropic-versionstring

The version of the Claude API you want to use.

Read more about versioning and our version history here.

The version of the Claude API you want to use.

Read more about versioning and our version history here.

Response

Successful Response

has_moreboolean required

Indicates if there are more results.

next_pagestring nullable required

Opaque cursor for the next page, or null when has_more is false. Pass it as the page parameter in the next request.

Example response

{
  "data": [
    {
      "starting_at": "2025-08-01T00:00:00Z",
      "ending_at": "2025-08-02T00:00:00Z",
      "results": [
        {
          "uncached_input_tokens": 1500,
          "cache_read_input_tokens": 200,
          "output_tokens": 500,
          "server_tool_use": {
            "web_search_requests": 10
          },
          "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
          "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
          "account_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
          "service_account_id": "svac_01Hk3R9TWxq7CfQak00OiVw4",
          "model": "claude-opus-5"
        }
      ]
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}

Changes