[DOCS] Missing `model_usage` field in Python SDK `ResultMessage` despite being documented in Cost Tracking

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Section: 4. Per-Model Usage Breakdown

Current Documentation

The documentation states:

"The result message also includes modelUsage, which provides authoritative per-model usage data. Like total_cost_usd, this field is accurate and suitable for billing purposes... result.modelUsage is a map of model name to ModelUsage"

It also provides a TypeScript type definition for ModelUsage but omits the Python equivalent, despite implying support across the SDK.

What's Wrong or Missing?

There is a discrepancy between the documentation and the actual Python SDK source code.

1. Missing Type Definition: In src/claude_agent_sdk/types.py, the ResultMessage dataclass does not contain a model_usage or modelUsage field.
2. Parser Logic: In src/claude_agent_sdk/_internal/message_parser.py, the parse_message function for case "result" does not attempt to extract model_usage from the incoming JSON data.

This means that developers following the "Tracking Costs and Usage" guide for Python will find that the ResultMessage object returned by query() or ClaudeSDKClient does not actually contain the per-model breakdown described.

Suggested Improvement

The documentation should be updated to reflect that this is currently a TypeScript-only feature, OR the Python SDK should be updated to match the documentation.

If updating the SDK, the following changes are needed:

In src/claude_agent_sdk/types.py:

@dataclass
class ResultMessage:
    # ... existing fields
    model_usage: dict[str, Any] | None = None # Add this field

In src/claude_agent_sdk/_internal/message_parser.py:

case "result":
    try:
        return ResultMessage(
            # ... existing mappings
            model_usage=data.get("model_usage") or data.get("modelUsage"), # Add this
        )

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: Agent SDK reference - Python
• Code Evidence: In the current Python SDK (v0.1.20), ResultMessage is defined as:

@dataclass
class ResultMessage:
    subtype: str
    duration_ms: int
    duration_api_ms: int
    is_error: bool
    num_turns: int
    session_id: str
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None
    structured_output: Any = None

• Comparison: The TypeScript SDK includes this field in its SDKResultMessage type, suggesting a parity gap that makes the cross-SDK "Cost Tracking" documentation technically incorrect for Python users.