Text caching
Updated
A cached text input token is a text token whose earlier processing System Zero reuses.
How reuse works
Text caching is automatic. An optional prompt_cache_key improves reuse within a workspace. Cache lifetime, minimum size and eviction are not published.
Keep shared leading text identical and reuse a stable prompt_cache_key for related work. The hint does not guarantee a cache hit.
Text caching is isolated by workspace. API keys in the same workspace share a cache partition.
Replaying a stored answer is different from reusing text processing. A stored replay adds no new input or cache usage to the totals.
Cached and uncached prices
| Input | Price per million input tokens |
|---|---|
| Uncached text input | USD 0.19 |
| Cached text input | USD 0.0172 |
Each million cached text tokens saves USD 0.1728 at these prices. This is a saving on text input, not a discount on the whole bill.
See Billing and credits for complete charges.
Read the text cache hit rate
Open Usage on your workspace's Overview, select a period and key, and read Cache hit rate (text). Calls by key shows each key's text cache hit rate for the selected period.
Add the counts before dividing. Text input is total input_tokens minus media_tokens and cached_media_tokens. Cached text is total cached_input_tokens minus cached_media_tokens.
Divide cached text by text input and multiply by 100. A selection can include media and still show a text rate when every row has all four counts measured.
Illustrative example with no media: 100 cached text tokens out of 100 text input tokens and 0 out of 900 combine to 10%, not 50%.
The 7-day and 30-day selections include today and use UTC bounds. Rates are rounded down to two decimal places; a positive rate below 0.01% reads less than 0.01%.
No data means a missing, invalid or inconsistent count, or no text input. Zero percent means measured text input with no cached text.
A period with no text input has no text rate. Negative or inconsistent counts make the rate unavailable.
Savings use the selected period's cached text tokens at current prices. They do not replace the billed total.
Usage fields and coverage
The console reads input_tokens, cached_input_tokens, media_tokens and cached_media_tokens from its usage data.
| Field | Meaning |
|---|---|
input_tokens | Total counted input, including reused input and media positions. |
cached_input_tokens | The reused part of the prompt, including any cached media positions. |
media_tokens | Uncached media positions, not files, seconds or pages. |
cached_media_tokens | Media positions served from cache. |
Older usage can return null for cached_media_tokens when any included hour was recorded before that count was measured. Missing or invalid counts make the rate unavailable for the whole selection.
Recent completed work can take time to appear. Failed requests add no tokens to these totals; successful requests with refused questions can still report measured tokens.
If the read fails, use Try again. A failed refresh keeps the last available data only for the same selection.