session/tokenUsage

A model call completed with usage: raw counters plus counted-once derivations plus session cumulative.

Parameters

Type: SessionTokenUsageParams

session/tokenUsage params: one per model completion that reports usage. Carries the raw counters verbatim plus the server-derived counted-once promptTokens/totalTokens and the session cumulative block. Accumulate-only: cumulative never goes backward.

Field	Type	Stability	Presence	Description
cumulative	CumulativeTokenUsage		required	Session running totals at this cursor; the fold owns the accumulation. Subagent/workflow-child usage is never folded in — it rides the owning items.
durationMs	integer		optional	Model-call wall time, when measured.
finishReason	string		optional	Provider finish reason when reported (open vocabulary, verbatim).
modelId	string		optional	The effective model that produced this usage; null on pre-schema records — never back-filled, an unpriced leg.
promptTokens	integer		required	Prompt tokens counted exactly once under the provider’s cache convention. Server-derived; deterministic — the provider is in the log.
sessionId	string		required	The owning session.
sourceRange	SourceRange		required	The durable records this event folded from.
totalTokens	integer		required	promptTokens + outputTokens — the honest per-completion total.
turnId	string		required	The turn whose model call completed.
usage	TokenUsage		required	Raw counters verbatim from the durable record.
viewCursor	string		required	Opaque, strictly monotonic view cursor.

Source

schema/msp/experimental/msp.schema.json#/notifications/session~2FtokenUsage

{
  "description": "A model call completed with usage: raw counters plus counted-once derivations plus session cumulative.",
  "params": {
    "$ref": "#/$defs/SessionTokenUsageParams"
  }
}