[DOCS] Logical inconsistency in SDK Cost Tracking: "usage" vs. "modelUsage"

Documentation Type

Unclear/confusing documentation

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/cost-tracking

Section/Topic

The Important Usage Rules section, specifically sub-points 3. Result Message Contains Cumulative Usage and 4. Per-Model Usage Breakdown.

Current Documentation

3. Result Message Contains Cumulative Usage The final result message contains the total cumulative usage from all steps in the conversation... 4. Per-Model Usage Breakdown The result message also includes modelUsage, which provides authoritative per-model usage data. Like total_cost_usd, this field is authoritative and suitable for billing purposes.

What's Wrong or Missing?

The documentation creates a logical conflict by labeling modelUsage as "authoritative" immediately after stating that result.usage contains the "total cumulative usage."

By using the word "authoritative" specifically for the model breakdown, it implies that the top-level usage object might be an estimate, non-authoritative, or potentially inaccurate for billing purposes. It fails to explicitly state the mathematical relationship between the two (i.e., whether usage is simply the sum of all entries in modelUsage).

Suggested Improvement

Clarify the relationship between these two objects. If both are accurate, the word "authoritative" should be used to describe the usage reporting of the ResultMessage as a whole, rather than pitting one field against the other.

Suggested Text:

3. Result Message Contains Aggregate Usage The final ResultMessage contains a usage object representing the total cumulative tokens used across all models and steps in the session. 4. Per-Model Usage Breakdown For granular tracking, the ResultMessage also includes modelUsage. This is a detailed breakdown of the aggregate usage object, categorized by specific model IDs. Both fields are derived from the same underlying billing data and are suitable for authoritative cost calculations.

Impact

High - Prevents users from using a feature

Additional Context

• Encountered in platform_claude_com_docs-part1.md during a review of SDK billing implementations.
• In financial/billing integrations, developers need to know which key is the "Source of Truth." If usage and sum(modelUsage) ever diverge (due to rounding or system-added tokens), the docs currently do not say which one takes precedence.