Caching

Note

When you don’t use caching (cache=true), storage (store=true) or similar options, screenshots are rendered on-demand and returned directly to you without being stored anywhere on ScreenshotOne infrastructure. This ensures maximum privacy for your rendered content. Except if you use response_type=json, in which case the screenshot is temporarily stored on ScreenshotOne servers to serve the screenshot URL for you.

During processing, rendered content may be stored temporarily.

Caching is free and available for all plans. However, it is not intended to be used in CDN-like scenarios. It is for you to save costs on rendering.

To use cache, the only option you need to set is cache=true:

https://api.screenshotone.com/take?url=https://example.com&cache=true&access_key=<access key>

Check out more cache options.

The default cache TTL is 4 hours. Set cache_ttl in seconds to extend it up to one month.

Caching is best-effort. If it fails, you still get the rendered file when possible. Successful synchronous JSON responses include screenshot_url; if none can be provided, the request returns an error. Caching is skipped for async=true and response_type=empty.

Requests served from cache don’t call webhooks. The webhook is only called when the screenshot is rendered.

When to use cache

The best usage of cache is to make rendering less expensive and faster, in case if you plan to render a lot of similar websites.

Cache key

Screenshots are cached by the combination of all specified request options. And the cache_key option allows having different cached versions of the same screenshot.

Impact on rendering quota

Requests served from cache do not count towards your rendering quota. A cache miss renders a new result and counts towards your quota.

HEAD requests use the same cache as GET. A HEAD request that misses the cache renders, counts towards your quota and stores the result, so you can use it to render ahead of time.

Cache URL

Note

Fetching the cache URL doesn’t trigger the rendering process. It is a direct link to the cached screenshot.

If you want to regenerate the cache, you need to make a new API request with the same parameters and if the cache is expired, it will be rendered again.

When caching succeeds, the x-screenshotone-cache-url response header provides a direct link to the cached image, PDF or video.

And if the response_type option is specified as json, you can find a cache URL in the JSON response too:

{
    "screenshot_url": "https://cache.screenshotone.com/...",
    "cache_url": "https://cache.screenshotone.com/..."
}

The cache URL lets you share a file without sharing your API key or setting up signed links. Each new render gets its own URL, so use the one from the latest API response and treat it as opaque. For downloads from JSON responses, use screenshot_url; it’s present even when cache_url is missing.

Cache TTL

Note

For long-term screenshot or video archival, consider uploading them to any compatible S3-storage.

The cache TTL is 4 hours by default. You can change it by specifying the cache_ttl option in seconds up to one month.

The TTL controls how long a result is reused. Once it expires, the next API request renders a new capture and counts towards your quota.

A cached file URL stays available at least until the TTL expires, but don’t rely on it for permanent storage.

Support

In case if you have any issues with caching or any ideas on how to improve it and make it better, please contact us at support@screenshotone.com.