Token usage and cost accounting: messageMetadata, cumulative usage, and per-feature attribution

TL;DR: Level 1: per-call usage. generateText/streamText results expose usage. You cannot manage what you do not measure. AI SDK 7 gives you usage at three levels; wire all three before the bill surprises you.

You cannot manage what you do not measure. AI SDK 7 gives you usage at three levels; wire all three before the bill surprises you.

Level 1: per-call usage. generateText/streamText results expose usage. In v7 the shape changed:

• usage.inputTokenDetails.cacheReadTokens (was usage.cachedInputTokens)
• usage.outputTokenDetails.reasoningTokens (was usage.reasoningTokens)
• result.usage accumulates across steps (was result.totalUsage)

Level 2: per-message metadata. Use the messageMetadata callback in toUIMessageStream to attach token counts and model id to each message:

toUIMessageStream({ stream: result.stream, messageMetadata ({ part }) => { if (part.type === 'start') return { createdAt: Date.now(), model: 'your-model-id' }; if (part.type === 'finish') return { totalTokens: part.totalUsage?.totalTokens }; }, });

Type the message as UIMessage[YourMetadata] with a zod schema for safety.

Level 3: per-feature attribution. Pass telemetry: { functionId: 'support-draft' } on every call so traces and cost dashboards group by feature.

Rules:

1. Migrate any code reading usage.cachedInputTokens or result.totalUsage. Those paths are gone in v7 and read as undefined, which silently zeroes your accounting.
2. Accumulate usage across steps for agentic calls; single-step usage understates tool-heavy turns badly.
3. Store per-message token counts in your chat store alongside the messages. Reconstructing cost from logs later is painful.
4. Alert on anomalies: a sudden 10x in input tokens usually means a context bug (whole history re-sent, or a runaway tool loop), not heavier usage.
5. Keep usage out of the client-visible payload unless the UI needs it. Token counts are operational data; expose only what the UI renders.

When to use

You hit exactly this: Token usage and cost accounting: messageMetadata, cumulative usage, and per-feature attribution in Token usage and cost accounting.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Token usage and cost accounting (versions mentioned here: v7).

Edge cases

• Those paths are gone in v7 and read as undefined, which silently zeroes your accounting.

Verified against the live AI SDK docs 2026-09-26. The v7 migration codemod table documents the usage renames (cachedInputTokens to inputTokenDetails.cacheReadTokens, reasoningTokens to outputTokenDetails.reasoningTokens) and totalUsage to usage. The message-metadata guide shows the messageMetadata callback with start/finish parts and typed UIMessage metadata. The telemetry guide documents functionId attribution.