Repository Public
1<!-- source: https://docs.x.ai/developers/advanced-api-usage/prompt-caching/multi-turn (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Prompt Caching34# What Breaks Caching56Any change to earlier messages breaks the cache. Only append new messages at the end.78> [!WARNING]9>10> **Keep messages unchanged.** For cache hits in multi-turn conversations, never edit, remove, or reorder earlier messages — only append new ones. For reasoning models, you **must** include `reasoning_content` from previous responses; omitting it is the top cause of cache misses.1112For reasoning models, you can maintain cache hits by either:1314* **Sending back the encrypted reasoning content** — Include the `reasoning_content` from the previous response. See [Encrypted Reasoning Content](/developers/model-capabilities/text/reasoning#encrypted-reasoning-content) for details.15* **Using stateful responses** — Use `previous_response_id` to automatically continue the conversation. See [Chaining the Conversation](/developers/model-capabilities/text/generate-text#chaining-the-conversation) for details.1617##  Cache hit — appending a new message1819The prompt prefix is identical to the previous request, with only a new user message appended:2021```bash customLanguage="bash" addedLines="26"22# Turn 1: Initial request (establishes the cache)23curl https://api.x.ai/v1/chat/completions \24 -H "Content-Type: application/json" \25 -H "Authorization: Bearer $XAI_API_KEY" \26 -H "x-grok-conv-id: conv_abc123" \27 -d '{28 "model": "grok-4.6",29 "messages": [30 {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},31 {"role": "user", "content": "What is prompt caching?"},32 {"role": "assistant", "content": "Prompt caching stores KV pairs from unchanged prompt prefixes so they can be reused on subsequent requests. This makes responses faster and cheaper."}33 ]34 }'3536# Turn 2: Cache HIT — exact prefix preserved, new message appended37curl https://api.x.ai/v1/chat/completions \38 -H "Content-Type: application/json" \39 -H "Authorization: Bearer $XAI_API_KEY" \40 -H "x-grok-conv-id: conv_abc123" \41 -d '{42 "model": "grok-4.6",43 "messages": [44 {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},45 {"role": "user", "content": "What is prompt caching?"},46 {"role": "assistant", "content": "Prompt caching stores KV pairs from unchanged prompt prefixes so they can be reused on subsequent requests. This makes responses faster and cheaper."},47 {"role": "user", "content": "Show me a code example."}48 ]49 }'50```5152```python customLanguage="pythonOpenAISDK"53from openai import OpenAI5455client = OpenAI(56 api_key="YOUR_XAI_API_KEY",57 base_url="https://api.x.ai/v1",58)5960conversation_id = "conv_abc123"61messages = [62 {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},63 {"role": "user", "content": "What is prompt caching?"},64]6566# Turn 1: Initial request (establishes the cache)67response = client.chat.completions.create(68 model="grok-4.6",69 messages=messages,70 extra_headers={"x-grok-conv-id": conversation_id},71)72print(f"Turn 1 — Cached tokens: {response.usage.prompt_tokens_details.cached_tokens}")7374# Append the assistant's reply and the next user message75messages.append({"role": "assistant", "content": response.choices[0].message.content})76messages.append({"role": "user", "content": "Show me a code example."})7778# Turn 2: Cache HIT — prefix is unchanged, only new messages appended79response = client.chat.completions.create(80 model="grok-4.6",81 messages=messages,82 extra_headers={"x-grok-conv-id": conversation_id},83)84print(f"Turn 2 — Cached tokens: {response.usage.prompt_tokens_details.cached_tokens}")85```8687```javascript customLanguage="javascriptOpenAISDK"88import OpenAI from 'openai';8990const client = new OpenAI({91 apiKey: 'YOUR_XAI_API_KEY',92 baseURL: 'https://api.x.ai/v1',93});9495const conversationId = 'conv_abc123';96const messages = [97 {98 role: 'system',99 content:100 'You are Grok, a helpful and truthful AI assistant built by xAI.',101 },102 { role: 'user', content: 'What is prompt caching?' },103];104105// Turn 1: Initial request (establishes the cache)106const turn1 = await client.chat.completions.create(107 { model: 'grok-4.6', messages },108 { headers: { 'x-grok-conv-id': conversationId } },109);110console.log(111 `Turn 1 — Cached tokens: ${turn1.usage.prompt_tokens_details.cached_tokens}`,112);113114// Append the assistant reply and next user message115messages.push({ role: 'assistant', content: turn1.choices[0].message.content });116117messages.push({ role: 'user', content: 'Show me a code example.' });118119// Turn 2: Cache HIT — prefix unchanged, new message appended120const turn2 = await client.chat.completions.create(121 { model: 'grok-4.6', messages },122 { headers: { 'x-grok-conv-id': conversationId } },123);124console.log(125 `Turn 2 — Cached tokens: ${turn2.usage.prompt_tokens_details.cached_tokens}`,126);127```128129##  Cache miss — editing an earlier message130131Changing the content of any earlier message breaks the prefix match:132133```bash customLanguage="bash" deletedLines="11" addedLines="12"134# Cache MISS — editing the assistant message content135curl https://api.x.ai/v1/chat/completions \136 -H "Content-Type: application/json" \137 -H "Authorization: Bearer $XAI_API_KEY" \138 -H "x-grok-conv-id: conv_abc123" \139 -d '{140 "model": "grok-4.6",141 "messages": [142 {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},143 {"role": "user", "content": "What is prompt caching?"},144 {"role": "assistant", "content": "Prompt caching stores KV pairs from unchanged prompt prefixes so they can be reused on subsequent requests. This makes responses faster and cheaper."},145 {"role": "assistant", "content": "It stores KV pairs."},146 {"role": "user", "content": "Show me a code example."}147 ]148 }'149```150151**What changed:** The assistant response on line 11 was shortened to `"It stores KV pairs."` (line 12).152153##  Cache miss — removing a message154155Removing any message from the conversation breaks the prefix:156157```bash customLanguage="bash" deletedLines="11"158# Cache MISS — the assistant message was removed159curl https://api.x.ai/v1/chat/completions \160 -H "Content-Type: application/json" \161 -H "Authorization: Bearer $XAI_API_KEY" \162 -H "x-grok-conv-id: conv_abc123" \163 -d '{164 "model": "grok-4.6",165 "messages": [166 {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},167 {"role": "user", "content": "What is prompt caching?"},168 {"role": "assistant", "content": "Prompt caching stores KV pairs from unchanged prompt prefixes so they can be reused on subsequent requests. This makes responses faster and cheaper."},169 {"role": "user", "content": "Show me a code example."}170 ]171 }'172```173174**What changed:** The assistant message on line 11 was removed entirely.175176##  Cache miss — reordering messages177178Changing the order of messages also breaks the prefix:179180```bash customLanguage="bash" deletedLines="9,10" addedLines="9,10"181# Cache MISS — user and system messages are swapped182curl https://api.x.ai/v1/chat/completions \183 -H "Content-Type: application/json" \184 -H "Authorization: Bearer $XAI_API_KEY" \185 -H "x-grok-conv-id: conv_abc123" \186 -d '{187 "model": "grok-4.6",188 "messages": [189 {"role": "user", "content": "What is prompt caching?"},190 {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},191 {"role": "assistant", "content": "Prompt caching stores KV pairs from unchanged prompt prefixes so they can be reused on subsequent requests. This makes responses faster and cheaper."},192 {"role": "user", "content": "Show me a code example."}193 ]194 }'195```196197**What changed:** Lines 9 and 10 were swapped — the user message now comes before the system message.198199## Next200201* [Usage & Pricing](/developers/advanced-api-usage/prompt-caching/usage-and-pricing)202