Clarify semantics of `assistant.usage.cost` in TypeScript SDK (estimated vs billable)

[schplitt]

Hi team 👋

I’m using the TypeScript SDK and collecting usage metrics from assistant.usage events (inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, cost).

I’m seeing cost values that appear inconsistent with expected billing and with the token profile of the run.
Before relying on this field, I’d like clarification in docs on what cost actually represents.

• What is the unit of assistant.usage.cost?
  • USD (e.g., dollars),
  • cents,
  • micro-dollars,
  • normalized/internal units,
  • or something else?
• Is assistant.usage.cost:
  • estimated cost,
  • normalized/internal units,
  • or actual billable cost?
• Is it guaranteed to match provider/GitHub billing, or only directional?
• Is it per-event incremental or cumulative per turn/session?
• How should consumers aggregate multiple usage events correctly?
• Are cache tokens already reflected in cost, and if so, how?
• Are there known cases where cost is omitted or less reliable?

Many of us are building observability dashboards and guardrails around SDK usage.
Without clear semantics (including units), users may misinterpret cost as invoice-accurate billing.

If there’s already guidance, a link would be super helpful. Otherwise, adding a short section to usage-event docs would prevent confusion.

Thanks!

[github-actions]

Thanks for opening this issue @schplitt! 👍

You've raised excellent questions about assistant.usage.cost semantics — units, aggregation behavior, and billing accuracy are all important for building reliable observability tooling.

I've labeled this as documentation and sdk/nodejs. The team will review and provide clarification on the usage event cost field semantics.

AI generated by Issue Triage Agent