On this page

Perplexity provides a dedicated Prompt Caching reference page for its Agent API (docs.perplexity.ai/docs/agent-api/prompt-caching), covering how reusable prompt prefixes are billed under Cache read and Cache write rates, how prompt_cache_key routes related requests for cache affinity, and how implicit and explicit modes control cache breakpoints. Earlier in August 2026, Perplexity introduced automatic stable prompt cache keys for Agent API presets (noting an estimated ~5% cost reduction for frequent preset usage); for related API coverage, see our guides on Perplexity Monitor API docs and pricing, Perplexity Decisions API updates, and the Perplexity provider hub.

Default Caching Behavior and Cache Read / Write Billing

By default, the Agent API places cache breakpoints on system instructions and the latest message, while underlying providers may also cache automatically—so single agent runs benefit without code changes. Each response reports cache metrics inside usage:

Cache Reads (input_tokens_details.cache_read_input_tokens): **Input tokens read from cache, billed at the model's **Cache read rate. For OpenAI compatibility, cached_tokens reports the same count, and charges appear in cost.cache_read_cost.

Cache Writes (input_tokens_details.cache_creation_input_tokens): **Input tokens written to cache, billed at the model's **Cache write rate (recorded in cost.cache_creation_cost). Per-model rates are published on the Agent API Models page; where a table lacks a Cache write column or displays an em dash, written tokens bill at the standard input rate.

Cost Warning on High Cache-Write Models: **On models whose Cache write rate exceeds the standard input rate—such as **openai/gpt-6.1-sol, listed on Perplexity's OpenAI pricing table at $2.00/1M input (<=272k) or $4.00/1M (>272k), $2.50/1M (<=272k) or $5.00/1M (>272k) Cache write, and "95% off input" for Cache read—writing an entire prompt to cache costs more than an uncached request unless subsequent requests read that prefix back.

The Agent API Models reference and pricing calculator include openai/gpt-6.2-sol and openai/gpt-6.2-astra at default-processing rates, and cache reads and writes are billed at the cache rates in that table, not the input rates; Perplexity channel rates for these two models are also noted in OpenAI Launches GPT-6.2 Astra and GPT-6.2 Sol Across ChatGPT Work, Codex, and the API.

Reusing Prefixes Across Requests With prompt_cache_key

For retries and multi-turn conversations, pass the same prompt_cache_key on every request that shares a prefix so requests route for cache affinity and hit prior writes:

**Account Scoping and Model Routing: **Keys are strictly scoped to your account—other accounts never share your cache affinity even if they send the same key string—and the key does not alter which model handles the request.

**Per-Workload Keys and Effort Overrides: **Assign one key per shared-prefix workload (such as one key per document or prompt template) and separate keys for unrelated workloads. Effort levels generate a default key for shared system prompts and tools, which an explicit prompt_cache_key overrides.

Prefix Ordering and Conversation Continuations: **Because cache reads require an exact prefix match, place static content (instructions, documents, schemas) at the start of the prompt and variable content at the end. Conversations can continue either by resending appended turns with the same key or by passing **previous_response_id so earlier turns reach the model unchanged.

Controlling Breakpoints With implicit and explicit Modes

Applications can customize cache boundaries via prompt_cache_options.mode and prompt_cache_breakpoint markers on input_text parts:

implicit Mode (Default): **Places default breakpoints and allows automatic provider caching. If you mark input_text parts with prompt_cache_breakpoint, your marks replace the default breakpoints (up to **3 marks per request).

explicit Mode: **Disables default breakpoints and automatic caching, caching only marked input_text parts (up to **4 marks per request). For one-off requests whose prefix will never be reused, sending "prompt_cache_options": {"mode": "explicit"} with no marks prevents cache-write charges.

Breakpoint Persistence, TTL, and SDK Typing: **Marking the input_text part at the end of a reusable prefix caches everything before it, including instructions and earlier messages. Marks persist across previous_response_id continuations (retaining the newest marks if the mode cap is exceeded), while exceeding the mark limit or marking non-input_text parts triggers an HTTP 400 error. Note that **prompt_cache_options.ttl is accepted for OpenAI compatibility and ignored—providers apply their own default cache lifetimes rather than OpenAI's configurable 12-hour TTL. When calling https://api.perplexity.ai/v1/agent, Perplexity's official Python and TypeScript examples note that prompt_cache_options and prompt_cache_breakpoint are not yet in the SDK types and should be passed via extra_body (Python) or @ts-expect-error (TypeScript).