ANanthropics

Get Messages Usage Report

Changed on

[Legacy] Get a report of your organization's Messages API usage, aggregated into time buckets.

This endpoint is part of the legacy Usage and Cost API. For new integrations, use GET /v1/organizations/analytics/usage in the Usage and Cost Analytics API instead. To move an existing integration, see Migrate from the Usage and Cost API.

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

Request

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
pagestring nullable

Optionally set to the next_page token from the previous response.

Example:page_MjAyNS0wNS0xNFQwMDowMDowMFo=
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
ending_atstring date-time nullable

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

Example:2024-10-30T23:58:27.427722Z
api_key_ids[]string[] nullable

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

workspace_ids[]string[] nullable

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

account_ids[]string[] nullable

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).

models[]string[] nullable

Restrict usage returned to the specified model(s).

service_tiers[]BetaUsageReportServiceTier[] nullable

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

[
  "standard"
]
context_window[]BetaMessagesUsageReportContextWindow[] nullable

Restrict usage returned to the specified context window(s). See the context_window response field for how a request is classified.

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.

speeds[]BetaSpeed[] nullable

Restrict usage returned to the specified speed(s).

group_by[]BetaMessagesUsageReportGroupBy[] nullable

Group by any subset of the available options.

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

Time granularity of the response data.

Headers

anthropic-versionstring

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_01WxYzAbCdEfGhJkMnPqRsTu",
          "service_account_id": "svac_01Hk3R9TWxq7CfQak00OiVw4",
          "model": "claude-opus-5-5",
          "service_tier": "standard"
        }
      ]
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}

Changes

  • 037a593978dcRevision changes
    • info

      added the enum value admin-user-sign-out-2026-10-08 to the property items/anyOf[subschema #2]/ of the header request parameter anthropic-beta

  • f538a797852cRevision changes
    • info

      added the enum value experimental-claude-tag-2026-10-21 to the property items/anyOf[subschema #2]/ of the header request parameter anthropic-beta