> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Caching

> Reuse eligible prompt input, understand cache discounts, and measure confirmed savings.

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:

```text theme={"system"}
2,000 / 1,000,000 × $1 = $0.002000
```

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**

```text theme={"system"}
Cached input:     1,500 / 1,000,000 × $0.10 = $0.000150
Remaining input:    500 / 1,000,000 × $1.00 = $0.000500
Total input charge:                         $0.000650
Input savings:     $0.002000 − $0.000650 =    $0.001350
```

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](https://nomask.ai/api/caching).

## 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`:

```json theme={"system"}
{
  "usage": {
    "prompt_tokens": 2000,
    "completion_tokens": 100,
    "total_tokens": 2100,
    "prompt_tokens_details": {"cached_tokens": 1500, "cache_write_tokens": 0}
  },
  "nomask": {
    "prompt_cache": {
      "enabled": true,
      "usage_status": "reported",
      "read_tokens": 1500,
      "write_tokens": 0,
      "usd_per_1m_cached_input": 0.1,
      "savings_usd": 0.00135
    }
  }
}
```

* `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](https://nomask.ai/api/caching) 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](https://docs.nomask.ai/privacy.md) for the separate optional response cache.

## Related guides

> [card] [Models](https://nomask.ai/models)
>
> Find current cached-input prices and supported features.

> [card] [Billing](https://docs.nomask.ai/billing.md)
>
> See how token usage and request-time prices become a charge.

> [card] [Privacy](https://docs.nomask.ai/privacy.md)
>
> Understand model processing and the separate optional retry cache.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.