On October 29, 2026, Anthropic launched the Usage and Cost Analytics API in beta. Claude Console and Claude Enterprise organizations can use the same usage and cost endpoints. The older endpoints remain supported.
An employee spending report can look complete while leaving out the service account running an agent. During this migration, a security team needs to check which identities its collector keeps, including consumption with no known actor.
This guide proposes a cutover procedure for that check. We have not exercised the API against a customer organization. The employee AI spending guide covers budgets and enforcement; this procedure checks whether the reporting behind those decisions is complete.
Choose the credential for the organization#
The shared endpoints do not merge Claude Console and Claude Enterprise accounts. Configure a separate collection job for each organization and record which credential supplies it.
For Claude Console, use a dedicated Admin credential. For Claude Enterprise, the primary owner enables API access at Organization settings → API and creates an Analytics API key with read:analytics. Store the credential in the collector's secret store. An application that generates inference requests should not need access to the reporting key. Follow Anthropic's analytics access instructions and the new API authentication requirements.
Check the billing plan before interpreting coverage. Anthropic documents cost and usage reporting for usage-based Enterprise plans; on seat-based Enterprise plans, the reports reflect usage credits. Neither is an inventory of employees' personal AI subscriptions. Enterprise eligibility.
For Claude Platform on AWS, use its regional endpoint and AWS authentication. Anthropic now documents both analytics endpoints, authorized through ListAccountUsage and ListAccountCost; each request covers workspaces in that endpoint's region. Record region as part of the collection scope. This is separate from Amazon Bedrock. AWS request setup and IAM actions.
See how your AI systems hold up under real attacks
General Analysis maps AI applications and agents, red teams prompts, retrieval, tools, MCP servers, browser actions, permissions, and business workflows, then turns findings into evidence your team can reproduce and retest.
Collect a total before assigning cost to people#
Start with a closed UTC period and two exports:
- An organization total with no grouping or identity filter.
- The same query grouped by
actor, preserving every returned actor type and the null row.
Keep the endpoint, credential scope, dates and all filters identical between them. Do not add actor_types[]=user_actor to the second export just because the old dashboard listed employees. The legacy per-user cost endpoint explicitly excludes cost without user attribution. Its sum is therefore the wrong baseline for whole-organization coverage.
The following request fetches the first page of the actor export. It uses September as a closed example period. Supply the appropriate reporting key through the environment; do not paste it into a notebook or article. The beta header's August date is its identifier, not the launch date.
Code source: Anthropic cost endpoint reference; adapted with illustrative collection parameters, not a recorded execution.
curl --fail-with-body --silent --show-error --get \
'https://api.anthropic.com/v1/organizations/analytics/cost' \
-H "x-api-key: $ANTHROPIC_ANALYTICS_KEY" \
-H 'anthropic-version: 2026-10-21' \
-H 'anthropic-beta: analytics-usage-cost-2026-08-24' \
--data-urlencode 'starting_at=2026-09-01T00:00:00Z' \
--data-urlencode 'ending_at=2026-10-01T00:00:00Z' \
--data-urlencode 'group_by[]=actor' \
--data-urlencode 'limit=1000'
For the total, omit only group_by[]=actor. For the actor export, follow next_page as the next request's page parameter while has_more is true, keeping every other parameter unchanged. A page-size limit does not establish completeness. If the cursor expires with HTTP 410, discard that attempt's partial staging data and restart collection; appending a fresh first page to old rows can double count cost. Pagination contract.
Save each complete export with its query, organization, collection time and data_refreshed_at. Commit the result to the reporting store only after the last page succeeds. This staging rule is our recommendation, not an API feature.
Interpret missing identity before filtering it#
An empty identity field can mean several things. Use the query that produced the row to decide which one applies.
| Observation | What the collector should retain |
|---|---|
actor is null and the query did not group by actor | The aggregate. This query never requested identity attribution. |
actor is null in an actor-grouped export | An explicit unattributed category, included in total cost. |
| An actor is a service account or an API key | That identity and its type. Do not force it into an employee record. |
api_key_id is null | The actor, if present. Some authenticated requests have no API key. |
| A grouped actor is a deleted user | The historical row, unless the report intentionally excludes deleted users. |
These distinctions follow Anthropic's actor model and Enterprise migration notes. Keep identity resolution separate from cost collection: a failed directory lookup should leave an unresolved owner, not remove the consumption record.
Suppose a service-account row has no match in your owner directory. Keep the amount and identifier, then ask the team responsible for that account to establish ownership. A guessed employee email makes the discrepancy disappear from the dashboard without resolving it.
Require agreement before replacing the collector#
Sum cost.amount across the complete actor export using decimal arithmetic, then compare it with the ungrouped total. Keep currency and cost basis identical. The cost schema defines amount in fractional cents after discounts and before credits; list_amount uses list prices. Neither field alone is the final invoice.
Compare the export timestamps too. Pagination stays within one query snapshot, but do not assume two separate queries saw the same refresh. If their data_refreshed_at values differ, recollect a matched pair before interpreting a discrepancy. A null watermark or one earlier than the period's end leaves coverage unresolved. Anthropic's freshness rules also allow later revisions, so timestamp agreement is a consistency check, not a promise of final billing.
Run these checks in a staging collector using saved exports and synthetic fixtures. They are acceptance criteria, not results from a General Analysis deployment:
| Case | Required outcome |
|---|---|
| The first page succeeds and a later page fails | No replacement of the last complete report; mark the new attempt incomplete. |
| The export contains an unattributed row | Its cost survives ingestion and contributes to the actor sum. |
| An owner lookup fails or a user was deleted | The cost remains visible, with unresolved or historical ownership. |
| A cursor expires mid-export | Restart into empty staging data; preserve the failed attempt's status. |
| Actor and total exports use different filters or refresh timestamps | Reject the comparison until the inputs match. |
| Complete, comparable exports disagree | Keep the existing collector and investigate parsing, units, duplicates and missing rows. |
Use actor-only grouping for this first gate. Add team, product and other views afterward, checking each dimension's semantics before treating its rows as an additive partition.
Agreement closes the cost-collection check for that organization and period. Authorization and unresolved account ownership still need their own evidence.
Keep immediate response on a separate evidence path#
Do not move an immediate abuse alarm to the new endpoint without reviewing its delay. Anthropic documents typical refresh within four hours, possible delay up to 24 hours, and revisions until about seven days after month end. Reporting freshness.
Use the aggregate report to investigate unexplained consumption and reconcile retained records. Use API telemetry for execution evidence and the Compliance API for supported activity and transcripts. Keep provider or gateway spending limits in place during the reporting cutover. A report that is late, empty or incomplete should raise a collection problem; it should not clear an account of suspicious activity or decide by itself to disable one.
Frequently asked questions
- Does a null actor mean nobody used Claude?
No. Without actor grouping, the field is null by design. With actor grouping, a null actor represents usage that the API cannot attribute to an identity. Keep that row in the total and investigate attribution separately.
- Can the new cost API replace an immediate abuse alert?
It is historical reporting with documented delays and later revisions. Use request or endpoint telemetry for immediate investigation and provider or gateway controls for spending enforcement. A low or empty cost result does not establish that no activity occurred.
- Do the legacy Claude reporting endpoints stop working?
Anthropic's October 29, 2026 release notes mark the older usage and cost endpoints as legacy and say they remain supported. Keep the existing collector during validation; the announcement does not impose a shutdown date.
