Anthropic Usage API: Make Claude Requests or Retrieve Usage and Cost

“Anthropic usage API” can mean two different tasks: sending a prompt to Claude or retrieving historical usage and cost data for an organization. For model responses, use the Messages API. For organizational reporting, use the Usage and Cost Analytics API. Anthropic recommends the Analytics API for new reporting integrations; its older Usage and Cost API is legacy but remains supported. (platform.claude.com)

Choose the API for your task

What you need	Use	What it does
Send a prompt and receive a Claude response	Messages API: POST /v1/messages	Sends conversational requests to a model. (platform.claude.com)
Review organizational token and request counts	Usage and Cost Analytics API: GET /v1/organizations/analytics/usage	Returns historical usage, optionally grouped by dimensions such as model or workspace. (platform.claude.com)
Review organizational cost	Usage and Cost Analytics API: GET /v1/organizations/analytics/cost	Returns historical cost in USD, with dimension breakdowns. (platform.claude.com)

The reporting endpoints are for organizations, not individual accounts. Credentials differ by organization type: Claude Console organizations use an Admin API credential; Claude Enterprise organizations use an Analytics API key with the read:analytics scope. (platform.claude.com)

Make a Claude API request

The Claude API is a REST API at https://api.anthropic.com; the Messages endpoint is POST /v1/messages. This example uses the model and API version shown in Anthropic’s current migration example. Keep the API key in a server-side environment variable. (platform.claude.com)

export ANTHROPIC_API_KEY="your-api-key"

curl --fail-with-body --show-error \
  https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Reply with the word OK."}
    ]
  }'

--fail-with-body makes curl return a failure status for an HTTP error while still showing the response body. A successful Messages response has type: "message", generated content in content, and request-level token information in usage. For this simple text request, the relevant fields look like this; the values below are illustrative, not the result of an executed request: (platform.claude.com)

{
  "type": "message",
  "role": "assistant",
  "content": [{"type": "text", "text": "OK"}],
  "usage": {"input_tokens": 12, "output_tokens": 2}
}

A non-success HTTP status means the smoke test failed; inspect the response body rather than treating printed JSON as a generated answer. In production, keep credentials server-side, handle API errors, and use limits that apply to your account. Track application request outcomes separately from organization-level reports.

Retrieve organizational usage and cost

The Usage and Cost Analytics API is in beta. Every request requires both anthropic-beta: analytics-usage-cost-2026-08-24 and an anthropic-version header. The usage endpoint returns token and request counts; the cost endpoint reports cost in USD. (platform.claude.com)

Select the reporting credential

• Claude Console organization: use an Admin API key or another Admin API credential. If using an OAuth token with org:admin, send it as Authorization: Bearer … instead of x-api-key.
• Claude Enterprise organization: use an Analytics API key with read:analytics, created by the primary owner after Analytics API access is enabled.
• Individual account: organization reporting is not available.

Use a separate environment variable for reporting credentials; do not assume the inference key is authorized for organization reports. Store reporting credentials securely and restrict their access. (platform.claude.com)

Example: daily usage grouped by model

For the Analytics API, use starting_at and ending_at as RFC 3339 timestamps; the start is inclusive and the end is exclusive. Use time_bucket_width=1d for daily buckets (1h and 1m are also documented widths) and repeat the array parameter as group_by[]=model. The Analytics API reference describes limit as page size; this example requests the first page only. (platform.claude.com)

export ANTHROPIC_ANALYTICS_KEY="your-authorized-admin-or-read-analytics-key"

curl --get "https://api.anthropic.com/v1/organizations/analytics/usage" \
  --data-urlencode "starting_at=2026-10-01T00:00:00Z" \
  --data-urlencode "ending_at=2026-10-08T00:00:00Z" \
  --data-urlencode "time_bucket_width=1d" \
  --data-urlencode "group_by[]=model" \
  --data-urlencode "limit=100" \
  -H "x-api-key: $ANTHROPIC_ANALYTICS_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24"

The response uses a data array. Each usage row contains starting_at, ending_at, a group object for requested dimensions, and a usage object for measures. For example, inspect data[].group.model for model attribution and fields under data[].usage for the returned token and request measures. Fields not requested as grouping dimensions may be null in group. (platform.claude.com)

To fetch costs, call /v1/organizations/analytics/cost and consult that endpoint’s reference for its cost-specific measures. Cost rows include a time range, group, and cost; the cost object documents amount, currency, list_amount, and requests. Anthropic describes amount as post-discount and pre-credit, and currency as USD. Do not interpret a usage token count as a monetary amount. (platform.claude.com)

Collect every page

Do not assume one response contains the complete report. Check has_more in each response. If it is true, take that response’s next_page value and send it as the page query parameter on the next request, preserving the same date range and filters. Repeat until has_more is false. Anthropic says its SDK and ant CLI handle the beta headers and retrieve remaining pages as results are read; with those tools, limit controls page size rather than total results. (platform.claude.com)

Interpret reports carefully

The Messages response’s usage object describes an individual request. The Analytics API provides historical, organization-level usage and cost reports; use its cost endpoint when you need reported monetary cost. A small, identifiable request can be a useful monitoring check against later organization activity, but the documentation describes historical data and does not establish a universal reporting delay. Do not treat a response’s token counts alone as a final billed total. (platform.claude.com)

Existing integrations: legacy Usage and Cost API

The older endpoints—/v1/organizations/usage_report/messages and /v1/organizations/cost_report—remain supported, but Anthropic labels them legacy and recommends the Usage and Cost Analytics API for new integrations. Existing integrations should follow Anthropic’s migration guidance rather than assuming the newer endpoints have identical response shapes. (platform.claude.com)

Before shipping

• Decide whether you need model inference, organizational reporting, or both.
• Use a Messages API key for model requests and the organization-appropriate credential for reporting.
• Include the required version header; add the documented beta header to Analytics API requests.
• Check has_more and continue with next_page until all report pages have been collected.
• Keep organization reporting credentials separate from application inference credentials, protected, and accessible only to the collector.
• Recheck Anthropic’s references when updating beta integrations or API versions.

Sources

API overview — Claude Platform Docs

Messages — Claude API Reference

Using the Messages API

Usage and Cost Analytics API

Get Token Usage By Dimension

Get Cost By Dimension

Python SDK: Get Token Usage By Dimension

Usage and Cost API

Migrating to API version 2026-10-21