SPB Git

Repository Public

usage-cost-api.md 16.3 KB 342 lines markdown

1---2title: Usage and Cost API3url: https://platform.claude.com/docs/en/manage-claude/usage-cost-api4description: Programmatically access your organization's API usage and cost data with the Usage & Cost Admin API.5---67<Tip>8  **The Admin API is unavailable for individual accounts.** To collaborate with teammates and add members, set up your organization in **Console → Settings → Organization**.9</Tip>1011The 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](https://platform.claude.com/usage) and [Cost](https://platform.claude.com/cost) pages of the Claude Console.1213This API enables you to better monitor, analyze, and optimize your Claude implementations:1415* **Accurate usage tracking:** Get precise token counts and usage patterns instead of relying solely on response token counting16* **Cost reconciliation:** Match internal records with Anthropic billing for finance and accounting teams17* **Product performance and improvement:** Monitor product performance while measuring if changes to the system have improved it, or set up alerting18* **[Rate limit](https://platform.claude.com/docs/en/api/rate-limits) optimization:** Optimize features like [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) or specific prompts to make the most of your allocated capacity.19* **Advanced analysis:** Perform deeper data analysis than what's available in Console2021<Check>22  **Admin API credentials required.** These endpoints are part of the Admin API. You can access them using an [Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys), an OAuth token with the `org:admin` scope, or a personal or service account key that isn't scoped to a workspace; workspace API keys don't work. See [Authentication](https://platform.claude.com/docs/en/manage-claude/admin-api#authentication) for details.23</Check>2425Claude Enterprise organizations use an Analytics API key with a different API instead; see [Which API do you need?](https://platform.claude.com/docs/en/manage-claude/usage-cost-api#which-api-do-you-need).2627<Note>28  **Claude Platform on AWS:** The programmatic Usage and Cost API endpoints are not currently available. View usage and cost data on the **Usage** and **Cost** pages in the Claude Console instead.29</Note>3031## Which API do you need?3233Anthropic provides cost and usage reporting through two APIs, depending on which Claude product your organization manages:3435| Your organization                | API                                                                                                                     | Key type                                                                                                                                           |36| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |37| Claude Console (Claude Platform) | The Usage and Cost Admin API described on this page                                                                     | Admin API key (`sk-ant-admin01-...`) or another [Admin API credential](https://platform.claude.com/docs/en/manage-claude/admin-api#authentication) |38| Claude Enterprise (claude.ai)    | The [Claude Enterprise Analytics API](https://platform.claude.com/docs/en/api/admin/analytics) cost and usage endpoints | Analytics API key                                                                                                                                  |3940Claude Enterprise parent organizations do not appear in Claude Console and carry no Admin API keys, so for them the Analytics API key is the only path to this data. See [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api) for how to create each key type and which plans the Claude Enterprise cost data applies to.4142## Partner solutions4344Leading 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.4546<CardGroup cols={3}>47  <Card title="CloudZero" icon="chart" href="https://docs.cloudzero.com/docs/connections-anthropic">48    Cloud intelligence platform for tracking and forecasting costs49  </Card>5051  <Card title="Datadog" icon="chart" href="https://docs.datadoghq.com/integrations/anthropic/">52    LLM Observability with automatic tracing and monitoring53  </Card>5455  <Card title="Grafana Cloud" icon="chart" href="https://grafana.com/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/integration-anthropic/">56    Agentless integration for easy LLM observability with out-of-the-box dashboards and alerts57  </Card>5859  <Card title="Harness" icon="chart" href="https://developer.harness.io/docs/cloud-cost-management/provider-integrations/ai-providers/anthropic/">60    FinOps platform for cloud and AI cost management61  </Card>6263  <Card title="Honeycomb" icon="polygon" href="https://docs.honeycomb.io/integrations/anthropic-usage-monitoring/">64    Advanced querying and visualization through OpenTelemetry65  </Card>6667  <Card title="Vantage" icon="chart" href="https://docs.vantage.sh/connecting_anthropic">68    FinOps platform for LLM cost & usage observability69  </Card>70</CardGroup>7172## Quick start7374Get your organization's daily usage for the last 7 days:7576```bash cURL77curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\78starting_at=2025-01-08T00:00:00Z&\79ending_at=2025-01-15T00:00:00Z&\80bucket_width=1d" \81  -H "anthropic-version: 2023-06-01" \82  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"83```8485<Tip>86  **Set a User-Agent header for integrations**8788  If you're building an integration, set your User-Agent header to help Anthropic understand usage patterns:8990  ```text wrap91  User-Agent: YourApp/1.0.0 (https://yourapp.com)92  ```93</Tip>9495## Usage API9697Track token consumption across your organization with detailed breakdowns by model, workspace, and service tier with the `/v1/organizations/usage_report/messages` endpoint.9899### Key concepts100101* **Time buckets:** Aggregate usage data in fixed intervals (`1m`, `1h`, or `1d`)102* **Token tracking:** Measure uncached input, cached input, cache creation, and output tokens103* **Filtering & grouping:** Filter by API key, workspace, model, service tier, context window, [data residency](https://platform.claude.com/docs/en/manage-claude/data-residency), or speed (beta), and group results by these dimensions104* **Server tool usage:** Track usage of server-side tools such as web search105106For complete parameter details and response schemas, see the [Usage API reference](https://platform.claude.com/docs/en/api/admin-api/usage-cost/get-messages-usage-report).107108### Basic examples109110#### Daily usage by model111112```bash cURL113curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\114starting_at=2025-01-01T00:00:00Z&\115ending_at=2025-01-08T00:00:00Z&\116group_by[]=model&\117bucket_width=1d" \118  -H "anthropic-version: 2023-06-01" \119  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"120```121122#### Hourly usage with filtering123124```bash cURL125curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\126starting_at=2025-01-15T00:00:00Z&\127ending_at=2025-01-15T23:59:59Z&\128models[]=claude-opus-5&\129service_tiers[]=batch&\130context_window[]=0-200k&\131bucket_width=1h" \132  -H "anthropic-version: 2023-06-01" \133  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"134```135136#### Filter usage by API keys and workspaces137138```bash cURL139curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\140starting_at=2025-01-01T00:00:00Z&\141ending_at=2025-01-08T00:00:00Z&\142api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\143api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\144workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\145workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\146bucket_width=1d" \147  -H "anthropic-version: 2023-06-01" \148  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"149```150151<Tip>152  To retrieve your organization's API key IDs, use the [List API Keys](https://platform.claude.com/docs/en/api/admin-api/apikeys/list-api-keys) endpoint.153154  To retrieve your organization's workspace IDs, use the [List Workspaces](https://platform.claude.com/docs/en/api/admin-api/workspaces/list-workspaces) endpoint, or find your organization's workspace IDs in the Claude Console.155</Tip>156157#### Data residency158159Track your [data residency controls](https://platform.claude.com/docs/en/manage-claude/data-residency) by grouping and filtering usage with the `inference_geo` dimension. This is useful for verifying geographic routing across your organization.160161```bash cURL162curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\163starting_at=2026-02-01T00:00:00Z&\164ending_at=2026-02-08T00:00:00Z&\165group_by[]=inference_geo&\166group_by[]=model&\167bucket_width=1d" \168  -H "anthropic-version: 2023-06-01" \169  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"170```171172You can also filter to a specific geo. Valid values are `global`, `us`, and `not_available`:173174```bash cURL175curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\176starting_at=2026-02-01T00:00:00Z&\177ending_at=2026-02-08T00:00:00Z&\178inference_geos[]=us&\179group_by[]=model&\180bucket_width=1d" \181  -H "anthropic-version: 2023-06-01" \182  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"183```184185<Note>186  Models released before February 2026 (prior to Claude Opus 4.6 and Claude Sonnet 4.6) don't support the `inference_geo` request parameter, so their usage reports return `"not_available"` for this dimension. You can use `not_available` as a filter value in `inference_geos[]` to target those models.187</Note>188189#### Fast mode (research preview)190191Track [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) usage by grouping and filtering with the `speed` dimension. This is useful for monitoring standard versus fast mode usage.192193```bash cURL194curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\195starting_at=2026-02-01T00:00:00Z&\196ending_at=2026-02-08T00:00:00Z&\197group_by[]=speed&\198group_by[]=model&\199bucket_width=1d" \200  -H "anthropic-version: 2023-06-01" \201  -H "anthropic-beta: fast-mode-2026-02-01" \202  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"203```204205You can also filter to a specific speed. Valid values are `standard` and `fast`:206207```bash cURL208curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\209starting_at=2026-02-01T00:00:00Z&\210ending_at=2026-02-08T00:00:00Z&\211speeds[]=fast&\212group_by[]=model&\213bucket_width=1d" \214  -H "anthropic-version: 2023-06-01" \215  -H "anthropic-beta: fast-mode-2026-02-01" \216  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"217```218219<Note>220  Both the `speeds[]` filter and the `speed` group\_by value require the `fast-mode-2026-02-01` beta header.221</Note>222223### Time granularity limits224225| Granularity | Default limit | Maximum limit | Use case               |226| ----------- | ------------- | ------------- | ---------------------- |227| `1m`        | 60 buckets    | 1,440 buckets | Real-time monitoring   |228| `1h`        | 24 buckets    | 168 buckets   | Daily patterns         |229| `1d`        | 7 buckets     | 31 buckets    | Weekly/monthly reports |230231## Cost API232233Retrieve service-level cost breakdowns in USD with the `/v1/organizations/cost_report` endpoint.234235### Key concepts236237* **Currency:** All costs in USD, reported as decimal strings in lowest units (cents)238* **Cost types:** Track token usage, web search, and code execution costs239* **Grouping:** Group costs by workspace or description for detailed breakdowns. When grouping by `description`, responses include parsed fields such as `model` and `inference_geo`240* **Time buckets:** Daily granularity only (`1d`)241242For complete parameter details and response schemas, see the [Cost API reference](https://platform.claude.com/docs/en/api/admin-api/usage-cost/get-cost-report).243244<Warning>245  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.246</Warning>247248### Basic example249250```bash cURL251curl "https://api.anthropic.com/v1/organizations/cost_report?\252starting_at=2025-01-01T00:00:00Z&\253ending_at=2025-01-31T00:00:00Z&\254group_by[]=workspace_id&\255group_by[]=description" \256  -H "anthropic-version: 2023-06-01" \257  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"258```259260## Pagination261262Both endpoints support pagination for large datasets:2632641. Make your initial request.2652. If `has_more` is `true`, use the `next_page` value in your next request.2663. Continue until `has_more` is `false`.267268```bash cURL269# First request270curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\271starting_at=2025-01-01T00:00:00Z&\272ending_at=2025-01-31T00:00:00Z&\273limit=7" \274  -H "anthropic-version: 2023-06-01" \275  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"276277# Response includes: "has_more": true, "next_page": "page_xyz..."278279# Next request with pagination280curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\281starting_at=2025-01-01T00:00:00Z&\282ending_at=2025-01-31T00:00:00Z&\283limit=7&\284page=page_xyz..." \285  -H "anthropic-version: 2023-06-01" \286  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"287```288289## Common use cases290291Explore detailed implementations in [Claude Cookbook](https://platform.claude.com/cookbook):292293* **Daily usage reports:** Track token consumption trends294* **Cost attribution:** Allocate expenses by workspace for chargebacks295* **Cache efficiency:** Measure and optimize prompt caching296* **Budget monitoring:** Set up alerts for spending thresholds297* **CSV export:** Generate reports for finance teams298299## Frequently asked questions300301### How fresh is the data?302303Usage and cost data typically appears within 5 minutes of API request completion, though delays may occasionally be longer.304305### What's the recommended polling frequency?306307The API supports polling once per minute for sustained use. For short bursts (for example, downloading paginated data), more frequent polling is acceptable. Cache results for dashboards that need frequent updates.308309### How do I track code execution usage?310311Code 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.312313### How do I track Priority Tier usage?314315Filter 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.316317### What happens with playground usage?318319API usage from playground in the Claude Console (and from the legacy Workbench before it) is not associated with an API key, so `api_key_id` will be `null` even when grouping by that dimension.320321### How is the default workspace represented?322323Usage and costs attributed to the default workspace have a `null` value for `workspace_id`.324325### How do I get per-user cost breakdowns for Claude Code?326327Use the [Claude Code Analytics API](https://platform.claude.com/docs/en/manage-claude/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](https://platform.claude.com/docs/en/manage-claude/usage-cost-api#usage-api) to track token consumption as a cost proxy.328329## See also330331Use the Usage and Cost APIs to deliver a better experience for your users, manage costs, and preserve your rate limit. Learn more about some of these other features:332333* [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api)334* [Admin API reference](https://platform.claude.com/docs/en/api/admin)335* [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api) - Which analytics API and key type your organization needs336* [Pricing](https://platform.claude.com/docs/en/about-claude/pricing)337* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) - Optimize costs with caching338* [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) - 50% discount on batch requests339* [Rate limits](https://platform.claude.com/docs/en/api/rate-limits) - Understand usage tiers340* [Rate Limits API](https://platform.claude.com/docs/en/manage-claude/rate-limits-api) - Read your configured rate limits341* [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) - Control inference geography342
Files main
Menu

Theme