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

# LLM Caching

Planck caching stores complete eligible LLM responses so repeated requests can return faster and avoid duplicate provider calls.

<Note>
  Looking for provider-level caching? Learn about [Prompt Caching](/gateway/concepts/prompt-caching) to cache prompts directly on provider servers when supported.
</Note>

## How It Works

Planck builds a cache key from the request path, request body, selected cache headers, and optional cache seed. If a matching entry exists, the gateway can return the cached response. If not, the gateway sends the request to the provider and can store the response for future identical requests.

Cache behavior is request-scoped. You opt in with `Planck-Cache-Enabled`.

## Quick Start

```typescript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.inquantum.ai/v1",
  apiKey: process.env.PLANCK_API_KEY,
});

const response = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello world" }],
  },
  {
    headers: {
      "Planck-Cache-Enabled": "true",
      "Planck-Cache-Control": "max-age=3600",
    },
  }
);
```

```bash theme={null}
curl https://api.inquantum.ai/v1/chat/completions \
  -H "Authorization: Bearer $PLANCK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Planck-Cache-Enabled: true" \
  -H "Planck-Cache-Control: max-age=3600" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Hello world" }]
  }'
```

## Headers

<ParamField header="Planck-Cache-Enabled" type="string" required>
  Enables response caching for the request. Use `"true"` to enable.
</ParamField>

<ParamField header="Planck-Cache-Control" type="string">
  Sets cache duration. Use `max-age=<seconds>`, for example `max-age=3600`.
</ParamField>

<ParamField header="Planck-Cache-Bucket-Max-Size" type="string">
  Number of different responses to store for the same request key. This is useful for non-deterministic prompts.
</ParamField>

<ParamField header="Planck-Cache-Seed" type="string">
  Creates a separate cache namespace, such as a user id, organization id, environment, or test run id.
</ParamField>

<ParamField header="Planck-Cache-Ignore-Keys" type="string">
  Comma-separated JSON keys to exclude from cache key generation.
</ParamField>

<Info>
  Header values must be strings. For example, use `"Planck-Cache-Bucket-Max-Size": "3"`.
</Info>

## Cache Seeds

Use a seed when the same request body should cache separately for different users, tenants, or environments:

```typescript theme={null}
await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Summarize my account." }],
  },
  {
    headers: {
      "Planck-Cache-Enabled": "true",
      "Planck-Cache-Seed": "user-123",
    },
  }
);
```

Changing the seed creates a separate cache namespace.

## Ignore Keys

Use `Planck-Cache-Ignore-Keys` for request fields that should not affect the cached response:

```typescript theme={null}
await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Explain caching." }],
    request_id: "req_123",
  },
  {
    headers: {
      "Planck-Cache-Enabled": "true",
      "Planck-Cache-Ignore-Keys": "request_id",
    },
  }
);
```

This is useful for timestamps, tracing ids, or other metadata fields that do not change the LLM output.

## Response Headers

When caching is enabled, inspect response headers to understand cache behavior:

| Header                    | Description                               |
| ------------------------- | ----------------------------------------- |
| `Planck-Cache`            | Cache status, such as `HIT` or `MISS`.    |
| `Planck-Cache-Bucket-Idx` | Cache bucket index used for the response. |

## Limitations

* Caching is intended for eligible JSON gateway requests.
* Streaming cache behavior may differ from non-streaming responses.
* Any non-ignored request body change creates a new cache key.
* Do not cache requests that include sensitive data unless your retention and privacy settings allow it.

## Related Features

<CardGroup cols={2}>
  <Card title="Prompt Caching" icon="server" href="/gateway/concepts/prompt-caching">
    Cache prompts on provider servers for reduced token costs and faster processing.
  </Card>

  <Card title="Custom Properties" icon="tag" href="/features/advanced-usage/custom-properties">
    Add metadata to requests for filtering and analysis.
  </Card>

  <Card title="Rate Limiting" icon="clock" href="/features/advanced-usage/custom-rate-limits">
    Control request frequency and combine with caching for cost optimization.
  </Card>

  <Card title="User Metrics" icon="chart-line" href="/features/advanced-usage/user-metrics">
    Track usage and savings by user or application.
  </Card>
</CardGroup>

***

<Accordion title="Need more help?">
  Additional questions or feedback? Reach out to
  [help@inquantum.ai](mailto:help@inquantum.ai) or [schedule a
  call](https://inquantum.ai/contact) with us.
</Accordion>