Skip to main content
Eligible models can reuse cached input. Confirmed cache reads are billed at the model’s configured cached-input rate.

​
Automatic caching

Send standard chat-completion requests. The API does not expose cache uploads or a selectable retention period. Cache availability depends on the model; repeating a prompt does not guarantee a hit.
  • Place stable instructions, tool definitions and reusable context before content that changes between requests.
  • Check capabilities.prompt_caching and pricing.usd_per_1m_cached_input_tokens in GET /models. A configured rate enables cache discounts; it does not guarantee that every request qualifies or a minimum hit rate.
  • A blank cached-input price disables cache discounts. It does not guarantee that automatic cache processing is disabled.

​
Charges and savings

Confirmed cache-read input uses the request’s cached-input rate. Remaining input, including cache writes, uses the ordinary input rate. Output keeps its own rate. Long-context pricing uses the model’s applicable request-time tier. Missing, invalid or estimated cache usage receives no inferred discount. A confirmed read count of zero is a measured miss. Rates and actual savings are frozen with the settled request; later model pricing changes do not reprice its history.

​
Example: a confirmed cache hit

These prices and token counts illustrate the calculation. Use your selected model’s current pricing and the counts reported for your request.
1

Check the model's input prices

Suppose the ordinary input rate is $1 per million tokens** and the cached-input rate is **$0.10 per million tokens. The cached rate applies only to confirmed cache reads on an eligible request.
2

Reuse a stable prompt prefix

Keep shared instructions, tool definitions, and reusable context at the beginning of your request. Put the new question after that shared content, then send a normal chat-completion request.In this example, the request contains 2,000 input tokens. Without a cache discount, the input charge would be:
Reusing content makes a request a candidate for caching; it does not guarantee a cache hit.
3

Read the confirmed cache usage

Suppose the response reports 1,500 cached input tokens. The remaining 500 input tokens use the ordinary input rate.Check nomask.prompt_cache.usage_status and read_tokens, or the confirmed count in usage.prompt_tokens_details.cached_tokens. The response example below shows these fields together.
4

Compare the settled input charge

Output charges are additional. Use nomask.prompt_cache.savings_usd for the actual rounded saving on the settled request, and compare requests in the Caching dashboard.

​
Reading cache results

Successful JSON responses include nomask.prompt_cache. Streams include the same metadata in the final usage chunk when stream_options.include_usage is enabled. Confirmed counts also appear in usage.prompt_tokens_details:
  • usage_status is reported, unreported, invalid, or estimated. Unknown read/write counts and unknown savings are null, not measured zero.
  • Read and write reporting are independent. A usage report may include one without the other; an absent cache_write_tokens does not mean no writes occurred.
  • enabled describes NoMask’s cached-price configuration. savings_usd is your actual rounded saving against the same request’s ordinary input price.

​
Measuring cache performance

The Caching tab charts cache use and saved USD, compares savings by model, and lets you inspect individual requests. Filter by dates, model or API key; CSV exports include the same selected records.
  • Request hit rate = requests with confirmed cache reads greater than zero ÷ confirmed enabled requests.
  • Input-token hit rate = confirmed cache-read tokens ÷ input tokens on those same requests. Daily and overall rates use token/request totals, not averages of percentages.
  • Unknown, legacy, disabled and estimated observations stay outside these denominators. Coverage is shown separately; no observations means “Not reported.”
  • Saved USD uses settled savings snapshots. Operating costs, unbilled failures, cache writes and account funding are not counted as your cache savings.

​
Privacy and retention

NoMask does not persist prompt bodies for this feature. Usage history stores cache counts, status, frozen prices and savings. Model processing may temporarily retain reusable input; retention varies by model. NoMask does not promise a universal cache lifetime. See Privacy for the separate optional response cache.

Models

Find current cached-input prices and supported features.

Billing

See how token usage and request-time prices become a charge.

Privacy

Understand model processing and the separate optional retry cache.