Caching & freshness
Scan-result caching, forceNew, and maxAgeHours.
CarbonFooter caches scan results in our database — not the target site's CDN or browser cache. The cached field in the response tells you which source served the data.
How caching works
- Normalize the requested
urlto form the cache key. - Scope the lookup to the current
methodology.scannerVersion— a scanner upgrade invalidates old rows. - If
forceNewistrue, skip the cache and always run fresh. - Otherwise, return the most recent stored scan if
scannedAtis withinmaxAgeHours(default 24). - If
screenshot: truewas requested but the cached scan has no screenshot, bypass the cache.
What counts as the same page
A stored scan matches your request when your URL equals either the URL that scan was requested with, or the URL the page ended up on after redirects. So all of these are served by one scan:
| You scanned | The page redirected to | Later requests that hit the cache |
|---|---|---|
example.com | https://www.example.com/ | example.com and www.example.com |
example.com/blog | https://example.com/blog/ | example.com/blog and example.com/blog/ |
URLs are otherwise compared exactly. /blog and /blog/ are only the same page if the site redirects one to the other, and different query strings are different pages. The fragment (#section) is ignored.
Caching and your limits
A result served from cache is never counted against your scan allowance, with or without an API key — only a new scan is. Leaving the cache on is the cheapest way to stay within your limits, and if you run out of scans you can still read every cached result.
The cache is shared: a result is a fact about a public page, so a scan another caller ran recently can answer your request.
A failed scan is never stored, so an error is never served from cache.
Request parameters
| Parameter | Default | Effect |
|---|---|---|
forceNew | false | Always run a fresh scan |
maxAgeHours | 24 | Maximum age of a cached result to serve. 0 to 720 (30 days); 0 never serves from cache |
# Serve cache up to 6 hours old
curl -s -X POST https://carbonfooter.nl/api/v2/scans \
-H 'Authorization: Bearer cf_live_…' \
-H 'Content-Type: application/json' \
-d '{"url": "example.com", "maxAgeHours": 6}'
# Always fresh
curl -s -X POST https://carbonfooter.nl/api/v2/scans \
-H 'Authorization: Bearer cf_live_…' \
-H 'Content-Type: application/json' \
-d '{"url": "example.com", "forceNew": true}'Response fields
| Field | Description |
|---|---|
cached | true if this response came from a stored scan |
scannedAt | When the measurement actually ran |
A cached response is shape-identical to a fresh one. If any field differs between cached and fresh paths, that is a contract bug.
When to use caching
| Scenario | Recommendation |
|---|---|
| Dashboard polling | Use default cache (maxAgeHours: 24) |
| CI on every commit | forceNew: true |
| Scheduled monitoring | Default cache with maxAgeHours matching your schedule |
| Screenshot capture | screenshot: true — may bypass cache if none stored |
Historical comparability
Scans taken before 2026-08-22 are not comparable with scans after that date due to methodology fixes (grid intensity, geolocation, rounding). See the compatibility policy.
How long scans are kept
Scans run with an API key are kept. Scans run without one are deleted after 30 days, together with their screenshot.