AnthropicClaude Certified Architect – Professional2026-104.6 Monitor system performance using logging and observability tools
Reconcile spend before charging product teams
Completed by the knowledge check
Learning objective
Track usage and cost trends and attribute spend by workspace, model, and feature.
Core idea
Maintain two connected views: provider-reported usage and cost, and application-owned feature allocation. The first describes what the provider reports for the organization. The second explains which product activity consumed it. Neither a token dashboard nor a workspace total alone provides defensible feature chargeback.
See 4.1.3 for cost per successful task. Here the architectural decision is how to collect, reconcile, and allocate the underlying spend so product and finance teams can explain a trend without confusing estimates with reported cost.
How it works
Collect the two reports at their supported grain
For organizations using the Claude Console, the Usage and Cost Admin API exposes two distinct endpoints. Their dimensions and time resolution differ:
| Report | Endpoint | Supported view relevant here |
|---|---|---|
| Usage | GET /v1/organizations/usage_report/messages | bucket_width=1m, 1h, or 1d; token categories grouped by dimensions including workspace, API key, and model |
| Cost | GET /v1/organizations/cost_report | Daily buckets only, bucket_width=1d; grouping by workspace or description, with parsed model information when grouping by description |
Use an Admin API key for this collector; workspace API keys do not work for these endpoints. Keep the credential with the reporting service rather than distributing it to every feature. The Admin API is unavailable for individual accounts. This is the Claude Console reporting path: Claude Enterprise uses a different analytics API, and the programmatic Usage and Cost API endpoints are unavailable on Claude Platform on AWS. There the documentation directs you to the Console’s Usage and Cost pages.
For token trends, request group_by[]=workspace_id and group_by[]=model, adding api_key_id where that subdivision is useful. For cost allocation by workspace and model, use group_by[]=workspace_id and group_by[]=description; inspect the returned parsed model rather than assuming the cost endpoint accepts the usage endpoint’s model grouping.
Cost is reported in USD as decimal strings in cents. Preserve that representation through ingestion with decimal arithmetic; a string containing cents must not become a dollar amount merely because a dashboard labels its axis USD. Keep currency and units in the stored schema and reconcile before presentation rounding.
Make ingestion complete and repeatable
Both endpoints paginate. Follow next_page using the page parameter while has_more is true. A successful first page is not a complete organization’s report. Record the requested interval, filters, grouping, retrieval time, and whether every page arrived.
Treat repeated collection as replacement or an upsert of the same bucket and dimension tuple, rather than appending every poll to the ledger. This is an application ingestion design: otherwise rereading a day doubles its apparent spend. Retain raw report batches or equivalent provenance so finance can trace a correction to its source.
Usage and cost data typically appears within five minutes after request completion, with longer delays possible. Sustained polling once per minute is supported. Mark the most recent interval provisional and reread overlapping intervals according to your reconciliation policy. The five-minute figure describes typical arrival, not a freshness guarantee or minute-level cost buckets.
Allocate features explicitly
Give each application operation a controlled feature identifier, such as catalog_assistance or return_resolution, when work begins. These are application labels, not provider report fields. Messages API metadata exposes only user_id, an opaque user identifier used to help detect abuse, not a feature tag. Usage report group_by has no feature or metadata dimension; grouping by its speed dimension requires the fast-mode-2026-02-01 beta header. Carry the application feature identifiers through model calls, retries, background work, and evaluation calls funded by that feature. Keep unassigned activity visible rather than distributing it invisibly across known features.
Choose allocation boundaries that match ownership. A workspace can isolate a product’s provider totals; separate API keys can help divide usage within that workspace. A feature sharing a key with other features still needs application records to divide its consumption. Reconcile those records to the provider’s workspace and model totals before accepting their allocation.
Record token categories separately, as 4.6.1 specifies, and attach the pricing assumptions used for any application cost estimate. A sum of tokens is not spend when input, output, cache reads, and cache creation have different rates. Do not force a disagreement to zero by changing rates until the totals happen to match. Classify it: missing operations, interval alignment, report lag, unassigned traffic, or a charge outside the estimate’s coverage.
Application records are reconciled to the provider’s workspace and model totals before their allocation is accepted, and a disagreement is classified rather than forced to zero.
The cost report includes token usage, web search, and code execution costs. Code execution is not included in the usage endpoint. Priority Tier costs are excluded from the cost endpoint; track its usage using service_tier with value priority and reconcile financial obligations separately. An otherwise complete token report cannot prove that every service charge has been allocated.
Explain the trend before optimizing it
Compare absolute spend, request volume, token categories per workflow, model mix, and feature share over aligned intervals. Keep failed attempts and background work in the numerator. A daily increase can reflect more useful work, a feature taking more turns, or a shift to more expensive work; only the segmented ledger distinguishes them.
Preserve null dimensions. The default workspace appears as workspace_id: null; playground usage can have api_key_id: null. Label those documented cases instead of dropping their rows as malformed. An allocation pipeline that discards nulls can produce a persuasive but incomplete chargeback.
Key distinctions and trade-offs
Provider-reported cost and an application estimate serve different purposes. Estimates support timely operating decisions and feature allocation; reported costs support reconciliation at the report’s documented coverage. Mark both clearly and assign an owner to unresolved differences.
More workspaces or keys can clarify ownership but increase credential and administration work. Application feature labels provide finer attribution without a credential per feature, but their completeness becomes your responsibility. Choose the simplest structure that keeps accountable teams and shared workloads distinguishable.
Architecture / decision scenario
A retailer shares one workspace across shopping assistance and return resolution. Daily reported cost rises from $400 to $640 while completed workflows grow only 10%. Finance proposes allocating the increase equally to both teams because they share a key.
The architect rejects equal allocation until the data is reconciled. Application records show shopping traffic and tokens per workflow are stable, while return resolution adds verification calls and shifts model mix. Those records allocate $210 of the $240 increase to returns and $30 to other activity. These are scenario figures, not provider prices.
The reporting owner retrieves every page, groups cost by workspace and description to inspect model detail, and reconciles the application’s feature shares with the daily total. A provisional recent bucket stays out of finalized chargeback; any unassigned discrepancy remains visible. The returns owner can then defend the additional spend using accepted-resolution outcomes, while finance avoids charging the shopping team for another feature’s change.
Common exam traps
- Assuming cost and usage support identical grouping or bucket widths.
- Treating decimal strings in cents as dollar amounts.
- Claiming a shared workspace or API key identifies a product feature.
- Tagging requests with
metadatato get feature spend in the cost report. - Summing repeated polls or retrieving only the first page.
- Treating five-minute typical availability as guaranteed real-time billing.
- Dropping null dimensions or assuming token usage includes every charge.
What to remember
Collect usage and cost at their own documented grains, preserve units and pagination, and reconcile before chargeback. Workspace and model explain provider totals; feature attribution requires an application-owned allocation that accounts for every funded operation and exposes unresolved differences.
Knowledge check
A finance team using the Claude Console needs reported daily cost — not an estimate — per workspace and per model from the Usage and Cost Admin API. The engineer plans to send the cost endpoint the group_by[]=model parameter that the usage collector already uses. Which request gives the model detail?
group_by[]=model with bucket_width=1h from the cost endpointworkspace_id and description ; read the parsed modelapi_key_id , then map each key to the model it callsmodel when grouped by description. Multiplying tokens by prices yields an estimate, and it misses charges such as code execution that the usage endpoint does not include.A cost collector reads a daily cost of "1250.5" for one workspace from the cost report, and the dashboard shows $1,250.50. Finance says that workspace’s share of the invoice for the day was about $12.51. What is the defect?
"1250.5" is $12.505. A hundredfold gap is a unit error, not a missing category or a double poll, which would at most double the figure. Keep the unit in the stored schema and use decimal arithmetic until presentation.Two product features share one workspace and one API key. The product lead wants spend per feature and proposes putting the feature name in metadata.user_id so the provider reports can split it. What should the architect do instead?
metadata to split each feature’s tokensapi_key_id to separate the two featuresmetadata.user_id is an opaque user identifier for abuse detection, and the usage report has no feature or metadata dimension. A shared key cannot separate features either. Feature attribution is application-owned: label each operation, including retries and background work, and reconcile the records to the provider’s workspace and model totals before charging anyone.A collector polls the cost report every hour and appends each response to the spend ledger. Monthly totals come out many times larger than the invoice. Which ingestion change fixes this?
References
- Anthropic, Usage and Cost API
- Anthropic, Prompt caching
- Anthropic, Create a Message
- Anthropic, Get Messages Usage Report