> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supercache

> Store reusable prompt prefixes for ultra low-cost reads

Supercache lets you reuse a prompt prefix for 24 hours. Write it once, then get
ultra low-cost reads for later requests with the same prefix.

Supercache is available with the Responses API and Chat Completions API.

## Pricing

Supercache uses separate read and write prices:

| Token group      | Price                                 |
| ---------------- | ------------------------------------- |
| Supercache read  | 10% of the regular cached-input price |
| Supercache write | 100 times the normal input price      |

Apply these multipliers to the cached-input and input prices on the
[Pricing](/pricing) page.

If regular cache and Supercache contain the same token, Sail uses the lower
Supercache read price.

<Warning>
  Supercache writes have a high one-time cost. Use them for large prefixes that
  you expect to read many times during the next 24 hours.
</Warning>

## Write a prefix

Set `metadata.supercache_write` to `"24h"`. This is the only accepted value.
Replace the placeholder below with at least 1,025 tokens of reusable content.

<CodeGroup>
  ```bash Responses API theme={null}
  curl -X POST https://api.sailresearch.com/v1/responses \
    -H "Authorization: Bearer YOUR_SAIL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org/GLM-5.2-FP8",
      "input": "<at least 1,025 tokens of reusable content>\n\nThe first question.",
      "background": true,
      "max_output_tokens": 16,
      "metadata": {
        "completion_window": "priority",
        "supercache_write": "24h"
      }
    }'
  ```

  ```bash Chat Completions API theme={null}
  curl -X POST https://api.sailresearch.com/v1/chat/completions \
    -H "Authorization: Bearer YOUR_SAIL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org/GLM-5.2-FP8",
      "messages": [
        {"role": "system", "content": "<at least 1,025 tokens of reusable content>"},
        {"role": "user", "content": "The first question."}
      ],
      "max_completion_tokens": 16,
      "metadata": {
        "completion_window": "priority",
        "supercache_write": "24h"
      }
    }'
  ```
</CodeGroup>

An explicit write takes priority over a read. If the prefix is already stored,
the request writes it again and starts a new 24-hour lifetime.

## Read a prefix

Sail automatically uses the longest matching stored prefix. Replace the
placeholder with the exact reusable content from the write request.

<CodeGroup>
  ```bash Responses API theme={null}
  curl -X POST https://api.sailresearch.com/v1/responses \
    -H "Authorization: Bearer YOUR_SAIL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org/GLM-5.2-FP8",
      "input": "<the same reusable content>\n\nA different question.",
      "background": true,
      "max_output_tokens": 16,
      "metadata": {
        "completion_window": "priority"
      }
    }'
  ```

  ```bash Chat Completions API theme={null}
  curl -X POST https://api.sailresearch.com/v1/chat/completions \
    -H "Authorization: Bearer YOUR_SAIL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org/GLM-5.2-FP8",
      "messages": [
        {"role": "system", "content": "<the same reusable content>"},
        {"role": "user", "content": "A different question."}
      ],
      "max_completion_tokens": 16,
      "metadata": {
        "completion_window": "priority"
      }
    }'
  ```
</CodeGroup>

A read does not extend the 24-hour lifetime. Only another explicit write starts
a new 24-hour lifetime.

## Usage fields

Completed Responses include two decimal-string metadata fields:

```json theme={null}
{
  "usage": {
    "input_tokens": 4609,
    "input_tokens_details": {
      "cached_tokens": 3072
    }
  },
  "metadata": {
    "supercached_input_tokens": "2048",
    "supercache_write_input_tokens": "0"
  }
}
```

* `metadata.supercached_input_tokens` is the number of tokens read from
  Supercache.
* `metadata.supercache_write_input_tokens` is the number of tokens written to
  Supercache.
* `usage.input_tokens_details.cached_tokens` includes both regular cached input
  and Supercache reads.

In this example, 2,048 tokens came from Supercache and 1,024 tokens came only
from regular cache.

Chat Completions reports the aggregate cached count in
`usage.prompt_tokens_details.cached_tokens`. It does not include the separate
Supercache read and write counts.