This article uses the supplied API usage reference and FAQ as related official Ollama documentation. Its proposed recordkeeping rules are application choices, not provider-prescribed accounting.
Separate the four dimensions
Start with four different meanings: a requested context setting, an observed input-token field, a cache-read token field, and a time field for uncached prompt evaluation. Keeping those meanings apart prevents a capacity setting or a duration from being relabelled as a token total.
The FAQ shows num_ctx as an API option. The usage reference describes prompt_eval_count as the input-token quantity and prompt_eval_cached_count as prompt tokens obtained from cache. It describes prompt_eval_duration as time spent evaluating uncached prompt tokens; timing metrics use nanosecond units.
The supplied excerpts do not define a conversion from num_ctx to prompt_eval_count, and they do not state whether the cached-count field is included within the prompt-count field. Treat both questions as unresolved until an application-specific validation rule has evidence beyond these excerpts.
Four-case collection decision table
Use this table as a proposed ingestion contract. “Evidence owner” identifies the component that should retain the evidence; it is not an assertion about Ollama’s internal ownership model.
| Case | Configuration evidence | Collection point | Prompt count | Cached count | Supported accounting conclusion | Inference to reject | Evidence owner | Bounded application-owned action |
|---|---|---|---|---|---|---|---|---|
| Configured context capacity with observed prompt usage | Store requested num_ctx separately. | Keep the response that supplies usage fields with its request record. | Record prompt_eval_count when supplied. | Record prompt_eval_cached_count when supplied. | Configuration and observed usage are distinct dimensions. | Requested context capacity equals observed prompt tokens. | Request recorder and response collector | Preserve both categories under separate names; leave an unavailable field null by local convention. |
| Non-streaming final response with cache metrics | Optional request record, if configured | Response body carrying usage metrics | Keep the reported field unchanged. | Keep the reported field unchanged. | Prompt and cache-read counts remain separate observations. | Add the two fields as independent token populations. | Response collector | Store raw values and prohibit a combined prompt-total column. |
| Intermediate streaming chunk | Optional request record, if configured | Before the terminal chunk | Do not designate a final prompt count from this collection point. | Do not designate a final cached count from this collection point. | The documented final-usage collection point has not yet arrived. | An earlier chunk is the final usage record. | Stream assembler | Mark final usage pending or absent according to the local missing-value policy. |
Final streaming chunk where done is true | Optional request record, if configured | Terminal chunk marked done=true | Record the terminal usage field when present. | Record the terminal cache-read field when present. | This is the documented streaming location for usage fields. | Use a prior chunk instead of the terminal record. | Stream assembler | Attach raw terminal fields to the completed request record without deriving a combined total. |
Withdraw the additive failure
Consider a hypothetical team that labels prompt_eval_count + prompt_eval_cached_count as one total. That label assumes the two values describe independent token populations, an assumption not established by the supplied material.
The repair is deliberately conservative: retain each raw API field, withdraw the previously labelled inflated result, and publish cache-read usage as a separate dimension. Do not replace the withdrawn value with another derived token total merely because both inputs have token-oriented names.
This is a proposed application remediation, not a documented Ollama outcome. Its purpose is to preserve auditability while the counting relationship remains unresolved.
Streaming and review boundaries
For streaming replies, the usage reference places usage fields in the ending chunk, identified by a true done value. An earlier chunk can support stream-progress handling, but it is not the documented location for final usage collection.
Define locally how nulls, interrupted streams, errors, and missing terminal fields are represented. Also define retention for the raw payload fields, a correction path for withdrawn derivatives, and a reviewer responsible for reconsidering the boundary after source changes or a version retirement or incompatible release.
Alternatives and limits
A semantic-dimension model is the recommended approach here: retain capacity, prompt count, cache-read count, and evaluation time in separate columns. A comparison rule may later be added by the application, but it should state its inputs, purpose, and validation evidence rather than silently changing the meaning of a source field.
An additive model is a viable data transformation only after separately validated evidence establishes the relationship it relies on; the supplied excerpts do not establish that relationship. This article is limited to those excerpts and does not claim behavior for earlier releases, every endpoint, interrupted requests, or fields absent from a response.