Caching

If you are capturing the same URL repeatedly, you can use caching to avoid redundant captures. When caching is enabled, the API checks whether a matching screenshot was already taken recently. If it was, the existing screenshot is returned instantly — no browser is launched, and no quota is consumed.

How It Works

1. You include the cache_ttl parameter in your capture request, specifying how many seconds a cached result should be considered valid.
2. The API checks for a previously captured screenshot with the same URL and same options taken within the cache window.
3. If a match is found, it is returned immediately. If not, a new screenshot is captured and stored in the cache for future requests.

The cache_ttl Parameter

Example: Cache for 1 Hour

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "cache_ttl": 3600
  }'

If you send the same request again within 3,600 seconds (1 hour), the API returns the existing screenshot immediately without re-rendering the page.

Example: Cache for 24 Hours

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=webp&cache_ttl=86400" \
  -o screenshot.webp

When to Use Caching

• Website thumbnails — if you show website previews in a directory or catalog, you probably don't need a fresh screenshot every time someone views the page. Cache for 24 hours.
• Link previews — for social sharing or link cards, cache for 1–6 hours.
• Repeated API calls — if your code might accidentally call the API multiple times for the same URL (e.g. in a loop with retries), caching prevents wasted quota.
• Static content — for pages that rarely change, a longer cache TTL saves the most quota.

When NOT to Use Caching

• Visual regression testing — you need a fresh screenshot every time to compare against the baseline.
• Change monitoring — the whole point is to detect changes, so caching would defeat the purpose.
• Dynamic content — if the page content changes frequently and you need to see the latest version, set cache_ttl=0 (the default).

Quota Savings