Caching

Ask for the same page twice and the second answer is the rendering we already made for you. It arrives faster and costs no credit. This page explains when that happens, how to tell that it did, and how to turn it off.

Caching is on unless you turn it off. If you are watching a page for changes, send cache=0 so every request renders the page as it is now.

How it works

A rendered file is kept under the exact request that produced it: the url, and every option you sent with it. Change any of them, a viewport, an image format, a selector, and you have described a different picture, so the page is rendered again. A screenshot and a PDF of one page are two entries for the same reason.

Entries belong to your own account. Nobody else's request is ever answered with a rendering you paid for, and yours is never answered with theirs, so what you render stays between you and us.

Identical requests that arrive at the same time are rendered once rather than once each. If you fan a batch of workers out over the same page, the first one renders it and the others are handed the result.

What it costs

A cached answer costs no credit. We render nothing, so there is nothing to charge for, and the answer arrives without waiting for a browser. It still counts as a request against your rate limit, which caps how fast you may ask rather than what asking costs.

Because a hit costs us nothing, it is served even when your credits have run out or your plan has lapsed. A request that has to render is refused in that situation; one we can answer from a rendering you already paid for is not.

Reading the headers

Every rendered answer says where it came from.

  • Name
    X-Cache
    Type
    string
    Description

    HIT means the file came out of the cache, so nothing was rendered and no credit was spent. MISS means the page was rendered for this request and the result was kept for the next one. The header is absent altogether when you sent cache=0: that request declined the cache rather than missing it.

  • Name
    ETag
    Type
    string
    Description

    A quoted fingerprint of the file itself, so two renderings that produced the same bytes carry the same tag. Keep it alongside whatever you did with the file and send it back on your next request to find out, for free, whether anything changed.

Asking whether anything changed

Send the ETag of the copy you already hold back as an If-None-Match header. If the entry is still the one that tag describes, the answer is 304 with no body at all: no credit, and no file to download a second time. Anything else is answered normally, with the file.

GET
/api/v1/snap 
curl "https://screenshotbuddy.io/api/v1/snap?url=https%3A%2F%2Fexample.com" \
  -H "Authorization: Bearer {token}" \
  -H 'If-None-Match: "<etag>"' \
  --output screenshot.png

How long a rendering is kept

A rendering is kept for 86400 seconds unless you say otherwise. Send cacheTtl, in seconds, to choose your own: at least 60 and at most 2592000, which is thirty days. Pick it from how often the page changes rather than from how often you ask: a marketing page can sit at the maximum, a dashboard should not.

Once the time is up the next request renders the page again, and costs a credit again.

Always rendering afresh

Send cache=0 and the page is rendered as it is right now. That request neither reads the cache nor fills it, it carries no X-Cache header, and it costs a credit like any other render. Sending cacheTtl alongside it is rejected with a 422: there is no lifetime to set on a rendering that is not being kept.

Try the options before you cache them

Get the request right in the browser first. A cached rendering is only as useful as the request that made it, and the playground is where you find out which options you actually want.

Open the playground