Notes from a response with extra usage fields

Usage fields are easy to ignore when a request succeeds. They become important when you need to explain a bill, compare prompts, measure a cache, or decide whether a response is worth storing. In a multi-protocol gateway such as Vana API, the same underlying request can expose usage information in different shapes depending on the protocol you use.

The useful question is not “Which response format is best?” It is “What decision will this field help me make?”

§ Start with the accounting question

Before parsing a response, decide whether you need an estimate or an authoritative record. A client-side estimate can help you reject an unusually large prompt before sending it. It cannot replace the usage returned by the service after generation.

For billing, quota enforcement, and durable reporting, use the response usage object as the source of record. Store the request identifier, model identifier, timestamp, and the complete usage object when practical. Do not calculate cost from visible text length. Tokens are shaped by the tokenizer, message structure, tool definitions, system instructions, and protocol details.

§ Choose fields for the decision

• Need total spend: keep input tokens, output tokens, and the total when the protocol provides it. Apply the rate for the selected model and preserve the rate version used for the calculation.
• Need to control prompt growth: track input tokens over time. A rising input count often points to an expanding conversation, repeated instructions, or tool schemas being sent on every turn.
• Need to control generation length: track output tokens and the finish reason together. A short output caused by a length limit is operationally different from a short answer that completed normally.
• Need to evaluate prompt caching: retain cached input tokens, cache creation tokens, or equivalent cache fields when present. Treat missing cache fields as “not reported,” not automatically as zero.
• Need to investigate reasoning cost: preserve reasoning or thinking token fields when the protocol exposes them. These tokens may not appear in the visible answer but can affect latency and billing.

§ Respect the protocol boundary

With Vana API, you can use the OpenAI-compatible endpoint, the Anthropic Messages protocol, or the Gemini native protocol. Their usage objects are not guaranteed to be interchangeable.

An OpenAI-compatible response commonly separates prompt or input tokens from completion or output tokens. An Anthropic Messages response may use input_tokens and output_tokens, with additional cache-related fields when applicable. Gemini responses may report promptTokenCount, candidatesTokenCount, and totalTokenCount, along with cached or thought-related counts depending on the model and request.

Build a small internal normalization layer if your application supports more than one protocol. Map fields into a stable record such as input tokens, output tokens, cached input tokens, reasoning tokens, total tokens, and raw usage. Keep the raw object because normalization can discard protocol-specific detail that becomes useful later.

§ Handle absent and changing fields carefully

Usage data can be absent when a request fails, when a streaming client has not processed the final event, or when a provider does not expose a particular metric. It can also vary by model and protocol. Use optional parsing, validate numeric values, and distinguish zero from null or missing.

For streaming, do not finalize accounting after the first text chunk. Read the terminal usage event or the final response according to the protocol. If your SDK does not expose that event, verify its behavior before using it for billing records.

§ Keep the raw record before optimizing

A practical stored record includes the protocol, model, request ID, input tokens, output tokens, total tokens, cache fields, reasoning fields, finish reason, and raw usage payload. Redact prompt and response content unless your retention policy requires it. Usage metrics are usually enough for cost analysis and are safer to retain.

Vana API bills per real token with no monthly fee, so these fields are useful for understanding actual request cost across supported providers and tools such as Claude Code, Codex, Gemini CLI, and OpenAI SDK clients. Create an account when you are ready to put the same accounting approach into a working integration.

§ A compact decision rule

If you are debugging a single request, inspect the raw usage object. If you are comparing requests, normalize the core token fields. If you are forecasting cost, store model-specific rates beside the recorded usage. If you are measuring caching or reasoning, preserve the protocol-specific fields rather than forcing them into a simplified total.