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.

Fields and variants

• cumulative
• durationMs
• finishReason
• modelId
• promptTokens
• sessionId
• sourceRange
• totalTokens
• turnId
• usage
• viewCursor

Source

schema/msp/experimental/msp.schema.json#/types/SessionTokenUsageParams

{
  "description": "`session/tokenUsage` params: one per model completion that\nreports usage. Carries the raw counters verbatim plus the server-derived\ncounted-once `promptTokens`/`totalTokens` and the\nsession `cumulative` block. Accumulate-only: `cumulative` never goes\nbackward.",
  "properties": {
    "cumulative": {
      "$ref": "#/$defs/CumulativeTokenUsage",
      "description": "Session running totals at this cursor; the fold owns the\naccumulation. Subagent/workflow-child usage is never folded in — it\nrides the owning items."
    },
    "durationMs": {
      "description": "Model-call wall time, when measured.",
      "type": "integer"
    },
    "finishReason": {
      "description": "Provider finish reason when reported (open vocabulary, verbatim).",
      "type": "string"
    },
    "modelId": {
      "description": "The effective model that produced this usage; `null` on pre-schema\nrecords — never back-filled, an unpriced leg.",
      "type": "string"
    },
    "promptTokens": {
      "description": "Prompt tokens counted exactly once under the provider's cache\nconvention. Server-derived; deterministic — the provider is\nin the log.",
      "type": "integer"
    },
    "sessionId": {
      "description": "The owning session.",
      "type": "string"
    },
    "sourceRange": {
      "$ref": "#/$defs/SourceRange",
      "description": "The durable records this event folded from."
    },
    "totalTokens": {
      "description": "`promptTokens + outputTokens` — the honest per-completion total.",
      "type": "integer"
    },
    "turnId": {
      "description": "The turn whose model call completed.",
      "type": "string"
    },
    "usage": {
      "$ref": "#/$defs/TokenUsage",
      "description": "Raw counters verbatim from the durable record."
    },
    "viewCursor": {
      "description": "Opaque, strictly monotonic view cursor.",
      "type": "string"
    }
  },
  "required": [
    "cumulative",
    "promptTokens",
    "sessionId",
    "sourceRange",
    "totalTokens",
    "turnId",
    "usage",
    "viewCursor"
  ],
  "type": "object"
}