SPB Git

Repository Public

usage-and-pricing.md 3.0 KB 92 lines markdown

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
Files main
Menu

Theme