Response caching: pay for a capture once
Turn on responseCache and identical requests return the stored result instead of rendering again. Here is how the TTL and nonce work, and when to use them.
Plenty of screenshot traffic is repetitive. A link preview is requested every time someone shares the link. A dashboard thumbnail is regenerated on every deploy. If the page has not changed, rendering it again is wasted time and wasted tokens.
Enabling the cache
{
"url": "https://example.com/pricing",
"responseCache": {
"enabled": true,
"ttl": 3600
}
}With enabled: true, a request whose parameters match a stored capture returns that capture immediately. The response includes fromCache: true so you can tell the difference.
What counts as "the same request"
The cache key is a hash of every parameter that affects the output: URL, format, quality, viewport, full-page, color scheme, blocking options and so on. Change any of them and you get a fresh render. The order of keys in your JSON does not matter.
Choosing a TTL
ttl is in seconds. It must be at least one minute and at most about a month; the default is one day.
- Social link previews - 1 day
- Marketing page thumbnails - 1 hour
- Status or pricing pages - 5 to 15 minutes
Forcing a fresh capture
Sometimes you know the page changed - you just deployed. Pass a nonce to bust the cache without turning it off:
{
"url": "https://example.com/pricing",
"responseCache": { "enabled": true, "nonce": "deploy-4812" }
}A new nonce means a new cache key. Use your commit SHA or release number and every deploy gets exactly one fresh capture.
Caching vs permalinks
Response caching is about saving work on repeated requests. If what you want is a stable URL that never expires, look at permalinks instead.