Administration and monitoring

Usage and Cost API

Programmatically access your organization's API usage and cost data with the Usage & Cost Admin API.

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

The Usage & Cost Admin API provides programmatic and granular access to historical API usage and cost data for your organization. This data is similar to the information available in the Usage and Cost pages of the Claude Console.

This API enables you to better monitor, analyze, and optimize your Claude implementations:

Accurate Usage Tracking: Get precise token counts and usage patterns instead of relying solely on response token counting
Cost Reconciliation: Match internal records with Anthropic billing for finance and accounting teams
Product performance and improvement: Monitor product performance while measuring if changes to the system have improved it, or setup alerting
Rate limit and Priority Tier optimization: Optimize features like prompt caching or specific prompts to make the most of one’s allocated capacity, or purchase dedicated capacity.
Advanced Analysis: Perform deeper data analysis than what's available in Console

Admin API key required

This API is part of the Admin API. These endpoints require an Admin API key (starting with sk-ant-admin...) that differs from standard API keys. Only organization members with the admin role can provision Admin API keys through the Claude Console.

Partner solutions

Leading observability platforms offer ready-to-use integrations for monitoring your Claude API usage and cost, without writing custom code. These integrations provide dashboards, alerting, and analytics to help you manage your API usage effectively.

Datadog

LLM Observability with automatic tracing and monitoring

Grafana Cloud

Agentless integration for easy LLM observability with out-of-the-box dashboards and alerts

Honeycomb

Advanced querying and visualization through OpenTelemetry

Quick start

Get your organization's daily usage for the last 7 days:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\ starting_at=2025-01-08T00:00:00Z&\ ending_at=2025-01-15T00:00:00Z&\ bucket_width=1d" \  --header "anthropic-version: 2023-06-01" \  --header "x-api-key: $ADMIN_API_KEY"

Set a User-Agent header for integrations

If you're building an integration, set your User-Agent header to help us understand usage patterns:

User-Agent: YourApp/1.0.0 (https://yourapp.com)

Usage API

Track token consumption across your organization with detailed breakdowns by model, workspace, and service tier with the /v1/organizations/usage_report/messages endpoint.

Key concepts

Time buckets: Aggregate usage data in fixed intervals (1m, 1h, or 1d)
Token tracking: Measure uncached input, cached input, cache creation, and output tokens
Filtering & grouping: Filter by API key, workspace, model, service tier, or context window, and group results by these dimensions
Server tool usage: Track usage of server-side tools like web search

For complete parameter details and response schemas, see the Usage API reference.

Basic examples

Daily usage by model

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\ starting_at=2025-01-01T00:00:00Z&\ ending_at=2025-01-08T00:00:00Z&\ group_by[]=model&\ bucket_width=1d" \  --header "anthropic-version: 2023-06-01" \  --header "x-api-key: $ADMIN_API_KEY"

Hourly usage with filtering

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\ starting_at=2025-01-15T00:00:00Z&\ ending_at=2025-01-15T23:59:59Z&\ models[]=claude-sonnet-4-5-20250929&\ service_tiers[]=batch&\ context_window[]=0-200k&\ bucket_width=1h" \  --header "anthropic-version: 2023-06-01" \  --header "x-api-key: $ADMIN_API_KEY"

Filter usage by API keys and workspaces

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\ starting_at=2025-01-01T00:00:00Z&\ ending_at=2025-01-08T00:00:00Z&\ api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\ api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\ workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\ workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\ bucket_width=1d" \  --header "anthropic-version: 2023-06-01" \  --header "x-api-key: $ADMIN_API_KEY"

To retrieve your organization's API key IDs, use the List API Keys endpoint.

To retrieve your organization's workspace IDs, use the List Workspaces endpoint, or find your organization's workspace IDs in the Anthropic Console.

Time granularity limits

Granularity	Default Limit	Maximum Limit	Use Case
`1m`	60 buckets	1440 buckets	Real-time monitoring
`1h`	24 buckets	168 buckets	Daily patterns
`1d`	7 buckets	31 buckets	Weekly/monthly reports

Cost API

Retrieve service-level cost breakdowns in USD with the /v1/organizations/cost_report endpoint.

Key concepts

Currency: All costs in USD, reported as decimal strings in lowest units (cents)
Cost types: Track token usage, web search, and code execution costs
Grouping: Group costs by workspace or description for detailed breakdowns
Time buckets: Daily granularity only (1d)

For complete parameter details and response schemas, see the Cost API reference.

Priority Tier costs use a different billing model and are not included in the cost endpoint. Track Priority Tier usage through the usage endpoint instead.

Basic example

curl "https://api.anthropic.com/v1/organizations/cost_report?\ starting_at=2025-01-01T00:00:00Z&\ ending_at=2025-01-31T00:00:00Z&\ group_by[]=workspace_id&\ group_by[]=description" \  --header "anthropic-version: 2023-06-01" \  --header "x-api-key: $ADMIN_API_KEY"

Pagination

Both endpoints support pagination for large datasets:

Make your initial request
If has_more is true, use the next_page value in your next request
Continue until has_more is false

# First request curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\ starting_at=2025-01-01T00:00:00Z&\ ending_at=2025-01-31T00:00:00Z&\ limit=7" \  --header "anthropic-version: 2023-06-01" \  --header "x-api-key: $ADMIN_API_KEY"  # Response includes: "has_more": true, "next_page": "page_xyz..."  # Next request with pagination curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\ starting_at=2025-01-01T00:00:00Z&\ ending_at=2025-01-31T00:00:00Z&\ limit=7&\ page=page_xyz..." \  --header "anthropic-version: 2023-06-01" \  --header "x-api-key: $ADMIN_API_KEY"

Common use cases

Explore detailed implementations in anthropic-cookbook:

Daily usage reports: Track token consumption trends
Cost attribution: Allocate expenses by workspace for chargebacks
Cache efficiency: Measure and optimize prompt caching
Budget monitoring: Set up alerts for spending thresholds
CSV export: Generate reports for finance teams

Frequently asked questions

How fresh is the data?

Usage and cost data typically appears within 5 minutes of API request completion, though delays may occasionally be longer.

What's the recommended polling frequency?

The API supports polling once per minute for sustained use. For short bursts (e.g., downloading paginated data), more frequent polling is acceptable. Cache results for dashboards that need frequent updates.

How do I track code execution usage?

Code execution costs appear in the cost endpoint grouped under Code Execution Usage in the description field. Code execution is not included in the usage endpoint.

How do I track Priority Tier usage?

Filter or group by service_tier in the usage endpoint and look for the priority value. Priority Tier costs are not available in the cost endpoint.

What happens with Workbench usage?

API usage from the Workbench is not associated with an API key, so api_key_id will be null even when grouping by that dimension.

How is the default workspace represented?

Usage and costs attributed to the default workspace have a null value for workspace_id.

How do I get per-user cost breakdowns for Claude Code?

Use the Claude Code Analytics API, which provides per-user estimated costs and productivity metrics without the performance limitations of breaking down costs by many API keys. For general API usage with many keys, use the Usage API to track token consumption as a cost proxy.

Partner solutions

Quick start

Usage API

Key concepts

Basic examples

Daily usage by model

Hourly usage with filtering

Filter usage by API keys and workspaces

Time granularity limits

Cost API

Key concepts

Basic example

Pagination

Common use cases

Frequently asked questions

How fresh is the data?

What's the recommended polling frequency?

How do I track code execution usage?

How do I track Priority Tier usage?

What happens with Workbench usage?

How is the default workspace represented?

How do I get per-user cost breakdowns for Claude Code?

See also