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

# Prompt Caching

> Reuse long prompt prefixes across Agent API requests, understand cache read and cache write billing, and control which prefixes are cached.

## Overview

Prompt caching reuses a prompt prefix that the model provider has already processed. Tokens read from the cache are billed at the model's **Cache read** rate. Tokens written to the cache are billed at its **Cache write** rate, which is above the input rate for some models. See [Models](https://docs.perplexity.ai/docs/agent-api/models.md) for both rates.

By default, the Agent API places cache breakpoints on the system instructions and on the latest message, and the provider may also cache automatically. You don't need to change anything to benefit from caching within one agent run.

## Billing

Every response reports cache usage in `usage`:

| Field | Meaning |
| - | - |
| `input_tokens_details.cache_read_input_tokens` | Input tokens read from the cache, billed at the **Cache read** rate. `cached_tokens` reports the same count, for OpenAI compatibility. |
| `input_tokens_details.cache_creation_input_tokens` | Input tokens written to the cache, billed at the **Cache write** rate. |
| `cost.cache_read_cost` / `cost.cache_creation_cost` | The cost of the cache reads and the cache writes. |

> [!WARNING]
>
> On models with a **Cache write** rate above the input rate, such as `openai/gpt-6.1-sol`, a request that writes its whole prompt to the cache costs more than the same request without caching. The write pays off only when later requests read the prefix back. Send a stable `prompt_cache_key`, and use [explicit mode](#control-what-is-cached) for prefixes you don't reuse.

## Reuse a prefix across requests

Send the same `prompt_cache_key` on every request that shares a prefix, including retries and multi-turn conversations. Requests with the same key are routed for cache affinity, so a later request can read the prefix an earlier one wrote.

* The key is scoped to your account. Other accounts never share your cache affinity, even if they use the same key.
* The key does not change which model handles the request.
* Use one key per workload that shares a prefix, such as one key per document or prompt template. Unrelated workloads should use different keys.
* [Effort levels](https://docs.perplexity.ai/docs/agent-api/effort.md) set a default key for their shared system prompt and tools. A key you send overrides it.
* Put content that stays the same (instructions, documents, schemas) at the start of the prompt and content that changes at the end. A cache read needs an exact prefix match.

To continue a conversation with the same key, either resend it with the new turns appended or pass `previous_response_id`. Earlier turns reach the model unchanged, so the new request can read the prefix the previous one wrote.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-6.1-sol",
    instructions="You are a contract analyst. Answer only from the contract text.",
    input="Contract: (long, stable document text)\n\nQuestion: Summarize the termination clause.",
    max_output_tokens=1024,
    # Reuse this key on every request that starts with the same contract.
    prompt_cache_key="contract-analysis-v1",
)

print(response.usage)
```

```typescript Typescript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
    model: "openai/gpt-6.1-sol",
    instructions: "You are a contract analyst. Answer only from the contract text.",
    input: "Contract: (long, stable document text)\n\nQuestion: Summarize the termination clause.",
    max_output_tokens: 1024,
    // Reuse this key on every request that starts with the same contract.
    prompt_cache_key: "contract-analysis-v1",
});

console.log(response.usage);
```

```bash cURL theme={null}
curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6.1-sol",
    "instructions": "You are a contract analyst. Answer only from the contract text.",
    "input": "Contract: (long, stable document text)\n\nQuestion: Summarize the termination clause.",
    "max_output_tokens": 1024,
    "prompt_cache_key": "contract-analysis-v1"
  }' | jq '.usage'
```

## Control what is cached

Use `prompt_cache_options.mode` and `prompt_cache_breakpoint` to choose which prefixes are written to the cache:

| Mode | Behavior |
| - | - |
| `implicit` (default) | The Agent API places its default breakpoints and the provider may cache automatically. If you mark `input_text` parts with `prompt_cache_breakpoint`, your marks replace the default breakpoints. Up to 3 marks per request. |
| `explicit` | No default breakpoints and no automatic caching. Only marked `input_text` parts are cached, up to 4 marks per request. With no marks, the request makes no cache writes. |

Put a mark on the `input_text` part that ends a reusable prefix. Everything before the mark, including the instructions and earlier messages, is cached with it. Marks are saved with the response, so a `previous_response_id` continuation keeps them; if a continuation ends up with more marks than its mode allows, the newest ones are used.

The API returns HTTP 400 if a request has more marks than its mode allows or marks a part other than `input_text`. `prompt_cache_options.ttl` is accepted for OpenAI compatibility and ignored: providers apply their default cache lifetime.

The example marks only the stable document, so the changing question is never written to the cache:

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-6.1-sol",
    max_output_tokens=1024,
    prompt_cache_key="contract-analysis-v1",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Contract: (long, stable document text)",
                    # Cache the prompt up to and including this part.
                    "prompt_cache_breakpoint": {"mode": "explicit"},
                },
                {"type": "input_text", "text": "Question: Summarize the termination clause."},
            ],
        }
    ],
    # prompt_cache_options is not in the SDK types yet; pass it in the request body.
    extra_body={"prompt_cache_options": {"mode": "explicit"}},
)

print(response.usage)
```

```typescript Typescript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
    model: "openai/gpt-6.1-sol",
    max_output_tokens: 1024,
    prompt_cache_key: "contract-analysis-v1",
    prompt_cache_options: { mode: "explicit" },
    input: [
        {
            role: "user",
            content: [
                {
                    type: "input_text",
                    text: "Contract: (long, stable document text)",
                    // Cache the prompt up to and including this part.
                    // @ts-expect-error prompt_cache_breakpoint and prompt_cache_options are not in the SDK types yet.
                    prompt_cache_breakpoint: { mode: "explicit" },
                },
                { type: "input_text", text: "Question: Summarize the termination clause." },
            ],
        },
    ],
});

console.log(response.usage);
```

```bash cURL theme={null}
curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6.1-sol",
    "max_output_tokens": 1024,
    "prompt_cache_key": "contract-analysis-v1",
    "prompt_cache_options": {"mode": "explicit"},
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Contract: (long, stable document text)",
            "prompt_cache_breakpoint": {"mode": "explicit"}
          },
          {"type": "input_text", "text": "Question: Summarize the termination clause."}
        ]
      }
    ]
  }' | jq '.usage'
```

> [!TIP]
>
> For one-off requests whose prefix is never reused, send `"prompt_cache_options": {"mode": "explicit"}` with no marks to avoid cache-write charges.

## Next Steps

> [card] [Agent API Models](https://docs.perplexity.ai/docs/agent-api/models.md)
>
> Compare input, cache read, and cache write rates.

> [card] [API Reference](https://docs.perplexity.ai/api-reference/agent-post.md)
>
> View complete endpoint documentation.
