The Usage & Cost Admin API has two halves. GET /v1/organizations/usage_report/messages reports token consumption; GET /v1/organizations/cost_report reports spend. Both require an Admin API key (sk-ant-admin01-...) and are organization-only. They look like siblings, but the cost endpoint plays by noticeably different rules — and treating it as "the usage endpoint, in dollars" produces reconciliation reports that quietly miss money in both directions.
Three mechanical differences from the usage endpoint
Daily granularity only. Where the usage endpoint offers 1m, 1h, and 1d buckets, the cost endpoint supports bucket_width: "1d" and nothing else. Cost is an accounting artifact, computed on a daily cycle — if you need intraday spend estimates, derive them yourself from token usage multiplied by list prices, and treat the result as an estimate rather than the ledger.
USD decimal strings, denominated in cents. Amounts come back as decimal strings in cents — a value like "12345.67" means $123.4567, not $12,345.67. The string-in-cents design avoids floating-point drift, but two bugs recur in home-grown tooling: parsing the string as dollars (inflating spend a hundredfold) and casting to a float before summing (rounding drift across thousands of rows). Parse with a decimal type and divide by 100 at the display layer only.
Two grouping options, not nine. The cost endpoint groups by workspace_id or description. Grouping by description adds parsed model and inference_geo fields to the results, which is how you approximate a per-model cost rollup. The usage endpoint's richer dimensions — API key, service tier, context window, and friends (see the dimensions guide) — do not exist here. If your chargeback needs per-key dollars, you compute them from per-key tokens and your pricing, not from this endpoint.
What the numbers won't include: Priority Tier
Priority Tier costs are absent from the cost endpoint. This is documented, not a bug: Priority Tier runs on a different billing model — committed capacity rather than pay-as-you-go per token — so its charges do not flow through this report. The endpoint's totals therefore understate organization spend for any org with Priority commitments. You can still see Priority activity: query the usage endpoint filtered to service_tiers[]=priority to track token volumes served at that tier, and reconcile the dollars against your commitment terms separately.
What appears only here: code execution
The inversion also runs the other way. Code execution costs appear only in the cost endpoint — under a "Code Execution Usage" description — and not in the usage endpoint at all. That makes sense once you know the billing unit: code execution is priced by sandbox runtime, not tokens, so a token-denominated usage report has nowhere to put it. The practical trap: a cost dashboard built purely on token math will miss code-execution spend entirely, while a "cost per token" metric computed as cost_report ÷ usage_report will drift upward as code-execution use grows. Keep tool-runtime charges as their own line.
| Usage endpoint | Cost endpoint | |
|---|---|---|
| Bucket widths | 1m / 1h / 1d | 1d only |
| Unit | Tokens (+ server-tool request counts) | USD decimal strings, in cents |
| Grouping | Nine dimensions | workspace_id or description |
| Priority Tier | Visible via service_tier | Absent (different billing model) |
| Code execution | Absent | Present ("Code Execution Usage") |
Freshness, polling, and platform scope
Like its sibling, the cost endpoint's data typically appears within about five minutes of request completion, supports sustained polling at once per minute, and paginates with has_more/next_page. Scope caveats: this is a first-party Claude API facility. On Claude Platform on AWS the programmatic endpoints are not available — the Console's Cost page (with CSV export) is the tool there (see the Platform-on-AWS exclusion). On Bedrock, Vertex, and Foundry, spend lives in the cloud's own billing systems — Cost Explorer, Cloud Billing, and Azure Cost Management respectively — with their own mechanics, such as Foundry's CCU meter.
Where to go next
Pair this with the three API key types to get authenticated, and finance reporting for Claude for turning these feeds into something your CFO signs off on.