Guides

Caching

Two caches can sit between you and the upstream: an API response cache that providers turn on for fast-changing market data, and an AI prompt cache that you turn on per request to cut the cost of repeated prompts.

	AI prompt cache	API response cache
Turned on by	You, per request (`X-Pikeway-Cache`)	The provider, per API
Applies to	Non-streaming chat completions	`GET` calls on `/gw/`
Shared	No, private to your account	Yes, by all callers
Price of a hit	10% of the token price	Normal per-call price

AI prompt cache

Agents often send the exact same prompt again: retries, loops, classification of repeated inputs. Add X-Pikeway-Cache to a non-streaming POST /ai/v1/chat/completions call and an identical request from your account within the TTL is answered from cache, without calling the model, at 10% of the original token cost.

bash

curl -i https://gw.pikeway.ai/ai/v1/chat/completions \
  -H "Authorization: Bearer $PIKEWAY_KEY" \
  -H "X-Pikeway-Cache: 300" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","temperature":0,"messages":[{"role":"user","content":"Classify: \"WBTC pumps 5%\""}]}'

# 1st call → X-Pikeway-Cache: MISS   X-Pikeway-Cost: 0.000210
# 2nd call → X-Pikeway-Cache: HIT    X-Pikeway-Cost: 0.000021   (10%, model not called)

Request header

X-Pikeway-Cacheseconds

How long to keep the response. Maximum 3600; 1 (or any non-number such as true) means 300 seconds; 0, false or no header turns caching off.

Response headers

X-Pikeway-CacheHIT | MISS

HIT: served from cache. MISS: the model was called and the response stored.

X-Pikeway-CostUSD

On a hit, 10% of what the cached response's tokens would cost.

What counts as identical

Same account and same model (aliases resolve to the same model), and the same request body apart from model, user, stream and stream_options. Key order in the JSON doesn't matter.
Matching is exact: change a single character of the prompt or any parameter (temperature, tools…) and it's a miss.
Caches are per account and never shared, so nobody can learn your prompts from cache timing.
Only key-authenticated, non-streaming chat completions are cached; the Messages and Responses endpoints, streams and x402 calls are not.

This is separate from the vendor's own prompt caching. When a model's provider reports cached input tokens, Pikeway bills those at the model's cache-read price automatically, with or without this header. See AI gateway.

API response cache

Providers can let the gateway cache successful GET responses of their API for a few seconds, for example prices or trending lists that every caller asks for at once. When it's on:

An identical GET (same API, path and query string) within the TTL is answered by the gateway in milliseconds, without calling the provider.
Responses carry X-Pikeway-Cache: HIT or MISS. Without the header, the API isn't cached.
Hits cost the same as a live call. You get a faster answer; the provider saves upstream cost.
The provider chooses the TTL (30 seconds unless set) and can limit caching to certain paths, so quotes, swaps and other per-request endpoints aren't cached.
Only successful responses are stored. POST requests and bring-your-own-key APIs are never cached.

bash

curl -i "https://gw.pikeway.ai/gw/<slug>/<path>" -H "Authorization: Bearer $PIKEWAY_KEY"

# X-Pikeway-Cache: HIT        ← served by the gateway, the provider wasn't called
# X-Pikeway-Cost: 0.0003      ← same price as a live call