Skip to Content
CarbonFooterv2.0

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

  1. Normalize the requested url to form the cache key.
  2. Scope the lookup to the current methodology.scannerVersion — a scanner upgrade invalidates old rows.
  3. If forceNew is true, skip the cache and always run fresh.
  4. Otherwise, return the most recent stored scan if scannedAt is within maxAgeHours (default 24).
  5. If screenshot: true was 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 scannedThe page redirected toLater requests that hit the cache
example.comhttps://www.example.com/example.com and www.example.com
example.com/bloghttps://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

ParameterDefaultEffect
forceNewfalseAlways run a fresh scan
maxAgeHours24Maximum age of a cached result to serve. 0 to 720 (30 days); 0 never serves from cache
Terminal
# 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

FieldDescription
cachedtrue if this response came from a stored scan
scannedAtWhen 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

ScenarioRecommendation
Dashboard pollingUse default cache (maxAgeHours: 24)
CI on every commitforceNew: true
Scheduled monitoringDefault cache with maxAgeHours matching your schedule
Screenshot capturescreenshot: 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.

On this page