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

A response that reads from or writes to the cache reports it 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. In the JSON response, each appears only when its token count is above zero. The SDK response objects show an absent field as `None` in Python and `null` in TypeScript. |

A request that neither reads from nor writes to the cache omits `cache_read_input_tokens`, `cache_creation_input_tokens`, and both cache costs. `input_tokens_details.cached_tokens` is still returned, with a value of `0`. A request with any cache activity returns both token fields, one of them possibly `0`, and only the cost fields whose count is above zero.

> [!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.
* A cache read needs the start of the prompt to match exactly. On OpenAI and Anthropic models, the default breakpoint on the latest message covers that whole message, so keep content that changes out of the message that holds your stable content. Put a stable document in an earlier message, or [mark it](#control-what-is-cached), and put the content that changes in the latest message. Keep `instructions` for your own rules.

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.

The example sends the contract in its own message and the question in the latest message, so a later request with a different question can read the contract from the cache. With both in one message, a new question changes the cached prefix: on OpenAI and Anthropic models, the request writes the whole prompt again and reads nothing.

```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=[
        # The contract stays the same on every request, so it gets its own message.
        {"type": "message", "role": "user", "content": "Contract: (long, stable document text)"},
        # The question changes, so it goes in the latest message.
        {"type": "message", "role": "user", "content": "Question: 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: [
        // The contract stays the same on every request, so it gets its own message.
        { type: "message", role: "user", content: "Contract: (long, stable document text)" },
        // The question changes, so it goes in the latest message.
        { type: "message", role: "user", content: "Question: 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": [
      {"type": "message", "role": "user", "content": "Contract: (long, stable document text)"},
      {"type": "message", "role": "user", "content": "Question: 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.
