Documentation can be updated for assistant.usage events

I have two suggestions for the Copilot SDK doc.

The online documentation page can add more details about the assistant.usage events. The SDK currently exposes all four numbers related to pricing "input tokens", "output tokens", "cache read tokens" and "cache write tokens". The documentation site only mentions input tokens and output tokens. copilot-usage-metrics
The online documentation and the TS SDK inline JSDoc can clarify what the "input tokens" number represent from the SDK events. I noticed that the number for "inputTokens" in my Copilot SDK events are abnormally high compared to the numbers reported by a Claude Agent SDK, making me suspect the "inputTokens" number actually includes tokens that are written to the cache. Given that new models have different price for input token and cache write tokens, the documentation should clarify that.

Thanks for the report. I confirmed the documentation gap and labeled this issue documentation.

Gap

assistant.usage docs list inputTokens and outputTokens, but cacheReadTokens and cacheWriteTokens are missing or underexplained. They appear only in docs/features/streaming-events.md and not in the usage-and-billing field table.
inputTokens is described only as "Input tokens consumed". It does not say whether it includes cache-read or cache-write tokens, so it is hard to compare with other SDKs or compute cost.

Affected files

docs/features/usage-and-billing.md (the assistant.usage field table near line 52, and the modelMetrics section near line 675)
docs/features/streaming-events.md (the field table near line 486, and the event summary table near line 1020, which omits the cache fields)
Inline JSDoc and doc comments for the generated assistant.usage event types in the SDKs. The fix belongs in the schema or generator inputs, not in hand-edited generated files.

Suggested fix

Document all four token fields (input, output, cache read, cache write) in both tables and in the modelMetrics.usage description.
State whether inputTokens includes cache-read and cache-write tokens, and how the four fields relate to billing. This needs confirmation from the runtime owners.
Add a short note on comparing these numbers with other SDKs, such as Claude Agent SDK, which report cached tokens separately.
Update the event summary table to include the cache fields.

Generated by Documentation Handler for #2834 · copilot · auto · 14.8 AIC · ⌖ 0.459 AIC · ⊞ 6.9K · ◷

Navigation Menu