RenderScreenshot

Caching

RenderScreenshot caches screenshots on a global CDN to improve performance and reduce costs.

How Caching Works

  1. Each unique URL + options combination generates a cache key
  2. First request renders the screenshot and stores it on CDN
  3. Subsequent requests serve from cache
  4. You only pay for renders, not cache hits

Cache Key

The cache key is based on:

  • Target URL
  • All screenshot options (viewport, format, etc.)
  • API key mode (live vs test)

Changing any option creates a new cache entry.

Default TTL

Screenshots are cached for 24 hours by default.

Controlling Cache

Return Cached Results

Opt into returning cached results from previous identical requests. When a cache hit is found, the response returns instantly with 0 credits used:

{
  "url": "https://example.com",
  "cache": {
    "available": true
  }
}

For GET requests, use cache_available=true:

GET /v1/screenshot?url=https://example.com&cache_available=true&api_key=rs_live_xxxxx

How it works:

  • Before calling the renderer, Rails checks for a recent successful request from the same account with identical rendering parameters within the cache TTL
  • Hit: Returns the existing screenshot URL, uses 0 credits, and sets cached: true in the response
  • Miss: Renders fresh and uses 1 credit as normal
  • Cache lookups are scoped per account — your cached results are never shared with other accounts
  • You still need at least 1 credit to make the request (in case of a cache miss)

Combine with cache.refresh to bypass the lookup and force a fresh render:

{
  "url": "https://example.com",
  "cache": {
    "available": true,
    "refresh": true
  }
}

Force Refresh

Bypass cache and force a new render:

{
  "url": "https://example.com",
  "cache": {
    "refresh": true
  }
}

Custom TTL

Set a custom cache duration (in seconds):

{
  "url": "https://example.com",
  "cache": {
    "ttl": 3600
  }
}

Maximum TTL is 30 days (2,592,000 seconds).

Disable Caching

Disable caching entirely for this request:

{
  "url": "https://example.com",
  "cache": {
    "enabled": false
  }
}

Note: This still counts as a render for billing purposes.

Cache Headers

Check cache status via response headers:

X-Cache-Status: HIT    # Served from cache
X-Cache-Status: MISS   # Fresh render

CDN URL

Every response includes an X-Cache-URL header with a public CDN link:

X-Cache-URL: https://cdn.renderscreenshot.com/screenshots/abc123.png

This URL:

  • Requires no authentication
  • Is safe for public HTML
  • Remains valid until the cache expires

Managing Cached Screenshots

You can retrieve, delete, and bulk purge cached screenshots using the cache management endpoints:

  • GET /v1/cache/:key - Retrieve a cached screenshot
  • DELETE /v1/cache/:key - Delete a single cache entry
  • POST /v1/cache/purge - Bulk delete by keys, URL pattern, or date

See Also

Was this page helpful?