Get Usage Report for the Messages API

Developer Guide

API Guide

Using the APIs

API reference

SDKs

Examples

3rd-party APIs

Using the Admin API

Support & configuration

GET

organizations

usage_report

messages

curl "https://api.anthropic.com/v1/organizations/usage_report/messages\
?starting_at=2025-08-01T00:00:00Z\
&group_by[]=api_key_id\
&group_by[]=workspace_id\
&group_by[]=model\
&group_by[]=service_tier\
&group_by[]=context_window\
&limit=1" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

{
  "data": [
    {
      "starting_at": "2025-08-01T00:00:00Z",
      "ending_at": "2025-08-02T00:00:00Z",
      "results": [
        {
          "uncached_input_tokens": 1500,
          "cache_creation": {
            "ephemeral_1h_input_tokens": 1000,
            "ephemeral_5m_input_tokens": 500
          },
          "cache_read_input_tokens": 200,
          "output_tokens": 500,
          "server_tool_use": {
            "web_search_requests": 10
          },
          "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
          "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
          "model": "claude-sonnet-4-20250514",
          "service_tier": "standard",
          "context_window": "0-200k"
        }
      ]
    }
  ],
  "has_more": true,
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}

The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers

x-api-key

string

required

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-version

string

required

The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Query Parameters

limit

integer

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

Examples:

7

page

string | null

Optionally set to the next_page token from the previous response.

Examples:

"page_MjAyNS0wNS0xNFQwMDowMDowMFo="

null

starting_at

string

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.

Examples:

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

ending_at

string | null

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

Examples:

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

api_key_ids[]

string[] | null

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

Examples:

"apikey_01Rj2N8SVvo6BePZj99NhmiT"

workspace_ids[]

string[] | null

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

Examples:

"wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"

models[]

string[] | null

Restrict usage returned to the specified model(s).

Examples:

"claude-sonnet-4-20250514"

"claude-3-5-haiku-20241022"

service_tiers[]

enum<string>[] | null

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

Available options:

standard,

batch,

priority

Examples:

"standard"

"batch"

"priority"

context_window[]

enum<string>[] | null

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

Available options:

0-200k,

200k-1M

Examples:

"0-200k"

"200k-1M"

group_by[]

enum<string>[] | null

Group by any subset of the available options.

Available options:

api_key_id,

workspace_id,

model,

service_tier,

context_window

Examples:

"api_key_id"

"workspace_id"

"model"

"service_tier"

"context_window"

bucket_width

enum<string>

Time granularity of the response data.

Available options:

1d,

1m,

1h

Response

200

application/json

Successful Response

data

object[]

required

data.starting_at

string

required

Start of the time bucket (inclusive) in RFC 3339 format.

Examples:

"2025-08-01T00:00:00Z"

data.ending_at

string

required

End of the time bucket (exclusive) in RFC 3339 format.

Examples:

"2025-08-02T00:00:00Z"

data.results

object[]

required

List of usage items for this time bucket. There may be multiple items if one or more group_by[] parameters are specified.

has_more

boolean

required

Indicates if there are more results.

next_page

string | null

required

Token to provide in as page in the subsequent request to retrieve the next page of data.

Examples:

"page_MjAyNS0wNS0xNFQwMDowMDowMFo="

null

Update API Keys Get Cost Report

curl "https://api.anthropic.com/v1/organizations/usage_report/messages\
?starting_at=2025-08-01T00:00:00Z\
&group_by[]=api_key_id\
&group_by[]=workspace_id\
&group_by[]=model\
&group_by[]=service_tier\
&group_by[]=context_window\
&limit=1" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

{
  "data": [
    {
      "starting_at": "2025-08-01T00:00:00Z",
      "ending_at": "2025-08-02T00:00:00Z",
      "results": [
        {
          "uncached_input_tokens": 1500,
          "cache_creation": {
            "ephemeral_1h_input_tokens": 1000,
            "ephemeral_5m_input_tokens": 500
          },
          "cache_read_input_tokens": 200,
          "output_tokens": 500,
          "server_tool_use": {
            "web_search_requests": 10
          },
          "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
          "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
          "model": "claude-sonnet-4-20250514",
          "service_tier": "standard",
          "context_window": "0-200k"
        }
      ]
    }
  ],
  "has_more": true,
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}