Repository Public
1<!-- source: https://docs.x.ai/developers/advanced-api-usage/prompt-caching/usage-and-pricing (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Prompt Caching34# Usage & Pricing56## Chat Completions API78Cached tokens appear in `usage.prompt_tokens_details.cached_tokens`:910```json customLanguage="json"11{12 "usage": {13 "prompt_tokens": 125,14 "completion_tokens": 48,15 "total_tokens": 173,16 "prompt_tokens_details": {17 "text_tokens": 125,18 "audio_tokens": 0,19 "image_tokens": 0,20 "cached_tokens": 9821 },22 "completion_tokens_details": {23 "reasoning_tokens": 0,24 "audio_tokens": 0,25 "accepted_prediction_tokens": 0,26 "rejected_prediction_tokens": 027 }28 }29}30```3132## Responses API3334Cached tokens appear in `usage.input_tokens_details.cached_tokens`:3536```json customLanguage="json"37{38 "usage": {39 "input_tokens": 125,40 "output_tokens": 48,41 "total_tokens": 173,42 "input_tokens_details": {43 "cached_tokens": 9844 },45 "output_tokens_details": {46 "reasoning_tokens": 047 }48 }49}50```5152## Verifying cache hits5354To determine whether your request benefitted from prompt caching, check the `cached_tokens` value in the response:5556| `cached_tokens` value | What it means |57|---|---|58| `0` | **Cache miss** — the entire prompt was computed from scratch. This is expected on the first request or after cache eviction. |59| `> 0` | **Cache hit** — some or all of your prompt prefix was served from cache. The number indicates how many tokens were reused. |60| Equal to `prompt_tokens` | **Full cache hit** — your entire prompt was served from cache (rare, typically happens when resending the exact same request). |6162A typical multi-turn conversation shows increasing `cached_tokens` over time:6364```text65Turn 1: prompt_tokens=50, cached_tokens=0 # First request, cache established66Turn 2: prompt_tokens=120, cached_tokens=50 # Previous 50 tokens cached67Turn 3: prompt_tokens=200, cached_tokens=120 # Previous 120 tokens cached68```6970> [!NOTE]71>72> If `cached_tokens` is consistently 0 across multiple requests in the same conversation, verify that you're setting `x-grok-conv-id` (or `prompt_cache_key`) and that you're not modifying earlier messages between requests.7374## Pricing7576Cached tokens are billed at the **cached prompt token price**, which is substantially lower than the regular prompt token price. The exact rates vary by model — check the [Pricing](/developers/pricing) page for current prices.7778| Token type | Billing rate |79|---|---|80| Prompt tokens (non-cached) | Full prompt token price |81| Cached prompt tokens | Reduced cached prompt token price |82| Completion tokens | Full completion token price |83| Reasoning tokens | Full completion token price |8485> [!NOTE]86>87> Long context pricing applies when total prompt tokens (including cached tokens) exceed the model's long context threshold. Both cached and non-cached tokens use their respective long-context rates in this case.8889## Next9091* [Best Practices & FAQ](/developers/advanced-api-usage/prompt-caching/best-practices)92