opendunes
Requests · 3 min
Copy page ▾

Response cache

Answer a request you have already sent from a kept copy, and pay nothing for it.

  1. Turn it on.
  2. Send the same request twice.
  3. Choose how long a copy lives.
  4. Ask for a fresh answer.

This is the deep guide. The headers, the status codes and what counts as identical sit in one place: Caching.

1. Turn it on

The cache is off until you turn it on. There are three ways, and they work on the same copies.

WayTurns it on for
the request header X-OpenDunes-Cache: truethat request
a preset that holds the cache: Presetsevery request that names the preset
the cache setting of a key, in your dashboardevery request of that key

A preset holds the cache beside the model and the parameters, so one name carries all of them.

When two ways disagree, the request's own header wins over the key's setting. X-OpenDunes-Cache: false switches the cache off for one request on a key that has it on.

Four routes cache: chat completions, responses, messages and embeddings.

Good to know

A copy is kept for one key only. A second key that sends the same body gets its own first answer from the model.

2. Send the same request twice

Souk Bot greets every visitor of a bookshop in Tlemcen with one line. This sample sends the greeting three times: twice as it is, then once asking for a fresh answer. It prints the cache status and the cost of each.

import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "One line to thank a customer of a bookshop in Tlemcen."

body = json.dumps(
    {"model": MODEL, "messages": [{"role": "user", "content": PROMPT}]}
).encode()

for clear in (False, False, True):
    headers = {
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
        "X-OpenDunes-Cache": "true",
    }
    if clear:
        headers["X-OpenDunes-Cache-Clear"] = "true"
    request = urllib.request.Request(ADDRESS, data=body, headers=headers)
    with urllib.request.urlopen(request) as response:
        answer = json.load(response)
        status = response.headers.get("X-OpenDunes-Cache-Status")
        print(status, answer["usage"]["cost"])

It prints MISS, then HIT, then MISS. The first request ran the model and kept its answer. The second came from the copy, at no charge, with no model running. The third asked for a fresh answer, so the model ran again and its answer replaced the copy.

Watch out

The copy is exact. Add a space to the prompt, or reorder two fields of the body, and the request is a new one: it prints MISS.

3. Choose how long a copy lives

A copy lives 300 seconds unless you say otherwise. Send X-OpenDunes-Cache-TTL with a whole number of seconds from 1 to 86400 to change it for the copy that request keeps. The key's cache setting in the dashboard holds a default span for the key.

UseSpan to ask for
a greeting or a fixed explanation that never changesa day: 86400
a summary of a page that changes during the dayan hour: 3600
an answer you only want to survive a retrythe default, or a few seconds
Do

Read X-OpenDunes-Cache-TTL on the answer to see how many seconds a hit has left. On a miss, it holds the full span.

4. Ask for a fresh answer

Send X-OpenDunes-Cache-Clear: true when one answer must be written again, such as after you have changed the text a prompt refers to. The model answers, you pay for that answer, and it replaces the kept copy for the next request.

Don't

Don't turn the cache on for a request that must read differently each time, such as a new product description on every call. Every hit returns the same words, whatever the temperature.

Errors

The body says why. What to do on every status: Errors and retries.

StatusMeans
400X-OpenDunes-Cache-TTL is not a whole number of seconds from 1 to 86400
401the key is missing or wrong
402the balanceBalanceWhat you can spend, in DA.More on Balance and charges → cannot cover a request that has to run the model