Skip to Content
CarbonFooterv2.0

Scan a page

POST /api/v2/scans — request body, parameters, and options.

Runs a synchronous scan and returns the complete result. Cached responses are shape-identical to fresh scans — check cached and scannedAt to tell them apart.

POST /api/v2/scans

Request body

interface ScanRequest {
  /** Page to scan. http(s) only; scheme optional, defaults to https. */
  url: string
  forceNew?: boolean
  maxAgeHours?: number
  screenshot?: boolean
  recommendations?: 'summary' | 'full'
  include?: IncludeMember[]
}

type IncludeMember =
  | 'thirdPartyDomains'
  | 'fontFamilies'
  | 'cacheByAsset'
  | 'videoEmbeds'
PropTypeDefaultDescription
urlstringRequired

Page to scan. Must be http or https and publicly reachable; the scheme is optional and defaults to https://. See URL rules.

forceNewbooleanfalse

Bypass the cache and always run a fresh scan.

maxAgeHoursnumber24

Serve a cached scan only if it is younger than this. 0 to 720; 0 never serves from cache. Ignored when forceNew is true.

screenshotbooleanfalse

Capture an above-the-fold WebP screenshot.

recommendations'summary' | 'full''summary'

Whether to include inline issue copy alongside the lean issue instances.

includeIncludeMember[][]

Opt-in detail lists. Unrecognised members are ignored.

Validation

Field types are strict. A string where a boolean belongs ("forceNew": "false") is rejected with 400 INVALID_REQUEST rather than guessed at, and error.details.fields names each offending field. null for an optional field means "not provided".

Values are lenient where that keeps old and new clients compatible: unknown include members, unknown recommendations values and unknown top-level keys are ignored.

URL rules

  • Only http and https. Any other scheme is 400 INVALID_URL.
  • URLs with embedded credentials (https://user:pass@…) are refused.
  • The fragment (#section) is dropped. Nothing else is rewritten — in particular a trailing slash is kept, since /blog and /blog/ are different URLs.
  • The URL must be on the public internet. localhost, private network ranges and other internal addresses are refused with 400 URL_NOT_ALLOWED, including when a public URL redirects to one.
  • The page must answer successfully. A URL that returns an error status gives 422 TARGET_ERROR instead of a measurement of the error page — see Errors.

Opt-in detail lists

Fields backed by an include member are null when not requested and [] when requested with no results. Unrecognised members are silently ignored, so new ones can be added without a version bump.

MemberPopulatesWhy it's opt-in
'thirdPartyDomains'thirdParty.domains[]Per-domain breakdown, typically 10–20 entries
'fontFamilies'assets.fonts.families[]Descriptive, not scored
'cacheByAsset'delivery.caching.byAsset[]Per-file cache headers, unbounded
'videoEmbeds'assets.video.embedded.providers[]Embed-focused breakdown

Example

Terminal
curl -s -X POST https://carbonfooter.nl/api/v2/scans \
  -H 'Authorization: Bearer cf_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "example.com",
    "screenshot": true,
    "recommendations": "full",
    "include": ["thirdPartyDomains", "cacheByAsset"]
  }'

Scanner behaviour

  • Pages are measured at a fixed 1440×900 viewport with deviceScaleFactor: 1.
  • Above the fold means resources loaded before any scrolling.
  • Full page means cumulative weight after auto-scrolling to the bottom.
  • The browser cache is disabled and every scan starts in a clean browser profile, so each one measures a cold first visit with no cookies or storage from an earlier scan.
  • A scan is limited to 50 seconds in total. A page that needs longer ends as 504 SCAN_TIMEOUT.
  • A page that never stops making requests (polling, streaming) is still measured: the scanner stops waiting for it and adds a SCROLL_TIMEOUT warning.
  • The scanner identifies as the desktop Chrome version it actually runs.
  • Two requests for the same page at the same time share one scan. When the scanner has no free slot, the request ends as 503 SCANNER_UNAVAILABLE with Retry-After and is not counted.
  • Requests carry X-CarbonFooter-Scan: 1 so site owners can allowlist the scanner.

Screenshots and the cache

If screenshot: true but the cached scan has no screenshot, the cache is bypassed and a fresh scan runs. When screenshot: false, the field is null even if a screenshot exists in storage.

The original /api endpoint

GET /api?target=<url> is the original, pre-v2 endpoint. It is still served, unchanged, for the plugins that were built on it, and returns its own older response shape — not the v2 response described here. It is frozen: nothing will be added to it. Build new integrations on /api/v2/.

On this page