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

# Response caching

> Opt-in per-workspace caching: identical requests are served instantly at a 75% discount.

Response caching is an **opt-in** workspace feature: when enabled, a
byte-identical request repeated within your chosen retention window is served
directly from the gateway's cache, with no model run, and billed at **25% of the
normal price** (a 75% discount). It's off by default.

## What a hit costs

The discount applies to the **whole request**, input *and* output tokens,
because no model ran at all. For a model priced at $1.40 input / $4.00 output
per 1M tokens:

|        | Normal      | Cache hit       |
| ------ | ----------- | --------------- |
| Input  | \$1.40 / 1M | **\$0.35 / 1M** |
| Output | \$4.00 / 1M | **\$1.00 / 1M** |

So a request with 1,000 input + 500 output tokens bills $0.0034 normally and **$0.00085\*\* as a hit. Every model's exact cache-hit price is shown in the
dashboard's model catalog (click any model).

<Note>
  This is a stronger discount than provider-side "cached input" pricing (the
  OpenAI/DeepSeek prompt-caching model), which discounts only the repeated
  input-prefix tokens while output still bills at full price. A response-cache
  hit discounts everything; the trade is that hits require the *entire*
  request to repeat byte-for-byte, and you opt into response retention.
</Note>

<Note>
  Caching is a per-workspace setting, and cached responses are **never shared
  across workspaces**: your cache entries are keyed to your workspace and are
  only ever returned to requests made with your keys.
</Note>

## Enabling it

In the [dashboard](https://platform.omnia-voice.com/dashboard) →
**Settings → Workspace → Response caching** (owner/admin only):

<Steps>
  <Step title="Turn on the toggle">
    Enabling takes effect within a few seconds across the gateway.
  </Step>

  <Step title="Pick a retention window">
    15 minutes, 1 hour (default), 6 hours, or 24 hours. Cached responses are
    deleted automatically when the window expires.
  </Step>
</Steps>

## What this stores: read before enabling

Omnia's default posture is content-free: we never retain your prompts or
completions. **Enabling caching changes that, by your choice**: model
responses (including their content) are kept in encrypted cache storage,
scoped to your workspace, for the retention window you chose, then deleted.
Request prompts are never stored as-is (cache keys are one-way hashes).
Nothing is stored while the toggle is off, and turning it off stops all reads
and writes immediately (existing entries simply expire).

## What gets cached

|                                                | Cached?                                                            |
| ---------------------------------------------- | ------------------------------------------------------------------ |
| Chat completions (streaming and non-streaming) | ✅ one entry serves both modes                                      |
| Embeddings                                     | ✅ the highest-hit-rate surface (deterministic, often re-requested) |
| Errors, partial or dropped streams             | ❌ never                                                            |
| Requests with `n > 1`                          | ❌ bypass the cache                                                 |
| Dedicated endpoints                            | ❌ not applicable: billed per GPU-hour, not per token               |

A hit requires the request to be **byte-identical**: same model, same
messages, same parameters. Changing `temperature`, adding a message, or
switching models produces a different cache key. Whether you set
`stream: true` or not does **not** change the key: a streamed request can be
served from a response that was first produced without streaming (it's
replayed as a normal SSE stream), and vice versa.

Using [fallback models](/inference/chat#fallback-models)? The `fallbacks`
list is part of the cache key, and only **primary-served** responses are
stored; a response produced by a fallback model is never cached, so a hit
always replays (and bills) the model the request asked for.

## Per-request control

With caching enabled on the workspace, individual requests can still opt out
with the `X-Omnia-Cache-Control` request header, useful for mixed workloads
(cache your eval suite and embeddings, keep production chat always-fresh):

```bash theme={null}
curl https://gateway.omnia-voice.com/v1/chat/completions \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -H "X-Omnia-Cache-Control: no-cache" \
  ...
```

| Directive  | Cache lookup                        | Stored afterwards?             |
| ---------- | ----------------------------------- | ------------------------------ |
| *(none)*   | ✅ normal: hit if present            | ✅ on a miss                    |
| `no-cache` | ❌ skipped: always a fresh model run | ✅ the cached copy is refreshed |
| `no-store` | ❌ skipped: always a fresh model run | ❌ never touches cache storage  |

Both directives answer with `X-Omnia-Cache: bypass`, and the request bills as
a normal (uncached) request. Use `no-store` for a call whose response you
don't want retained even though the workspace caches, for example a request
carrying sensitive data.

<Note>
  The header can only **reduce** caching, never enable it: with the workspace
  toggle off it does nothing (there is no per-request way to opt *in*, because
  enabling retention is a workspace-level decision).
</Note>

## How hits look

* Every cache-eligible response carries an `X-Omnia-Cache` header: `hit` when
  served from cache, `miss` when it went to the model. (Workspaces with caching
  off never see the header.)
* Streamed hits replay as standard SSE chunks ending in `data: [DONE]`, with
  the usual usage chunk.
* In your [usage ledger](/billing/usage) (and CSV export), hits appear as
  normal rows flagged as cached, billed at 25% of what the same request cost
  uncached. Token counts shown are the original response's real counts.

## When it pays off

Exact-match caching shines on repeated identical calls: RAG pipelines
re-embedding unchanged documents, evaluation and test suites, agent retries,
and templated prompts. Organic free-form chat rarely repeats byte-for-byte;
if your traffic is all unique prompts, leave caching off and nothing changes.