Caching strategies for screenshot APIs

Rendering a page in a real browser takes around a second or more. If you show the same screenshot to thousands of users — link previews, directory thumbnails, social cards — you don't want to render it every time. That's what caching is for.

Built-in edge caching

Add cache=true and the response is stored. Identical requests within the TTL are served from cache, instantly:

curl -G "https://api.screenshotdude.com/v1/capture" \
  --data-urlencode "url=https://example.com" \
  -d cache=true -d cache_ttl=86400 \
  -H "x-api-key: $SCREENSHOTDUDE_API_KEY" -I
# x-cache: MISS   (first request)
# x-cache: HIT    (subsequent requests)

• cache_ttl is in seconds. The default is one day (86,400) and the maximum is 30 days (2,592,000).
• The cache key includes all rendering parameters, so format=png and format=webp are cached separately.
• Check the x-cache response header to see whether you got a HIT or a MISS.

Picking a TTL

Layer your own cache in front

For high-traffic previews, put your CDN or object storage in front of the API:

1. Upload the capture to your own bucket with s3_url=true — you get JSON with the file URL.
2. Store the URL in your database next to the source URL and a timestamp.
3. Serve the image from your CDN. Refresh it in the background when it's older than your TTL.

This pattern ("stale-while-revalidate") keeps pages fast even when a refresh is in progress.

Busting the cache

Need a fresh capture right now? Send the request without cache=true — it always renders a new screenshot. You can also vary a harmless parameter, but explicit is better.

Don't forget the costs

Cache hits are still counted as requests, but they return instantly and never consume rendering time, so they make your latency — and your infrastructure — predictable. Combine caching with the pricing calculator to size your plan.

More details in the caching guide.