Skip to Content
CarbonFooterv2.0

Response structure

Namespaces, top-level fields, and what each section means.

Every successful scan returns a ScanV2Response object. All fields are always present — unavailable values are null or [], never omitted.

Top-level identity

FieldDescription
versionContract version ("2.0"). Not the scanner version — see methodology.scannerVersion.
scanIdOpaque identifier. Never parse it.
status"completed" in sync mode. "pending" and "failed" reserved for future async support.
cachedtrue when served from our scan-result cache (not the target site's CDN cache).
urlFinal URL after redirects.
websiteHostname (e.g. blog.example.com). Subdomains are tracked separately.
scannedAtISO-8601 timestamp of when the measurement ran.
gradeA+ through F, derived from co2.perVisit.

co2 — headline emissions

FieldDescription
perVisitCanonical emissions for one visit. Drives grade.
perByteEmissions per transferred byte under the same grid assumptions.
range.minAbove-the-fold emissions — floor for visitors who never scroll.
range.maxFull-page emissions — ceiling for visitors who scroll to the bottom.

perVisit equals one of the range endpoints, selected by methodology.basis. Today the basis is fullPage, so perVisit === range.max.

measurement — resources by phase

Three phases, identical shape:

  • aboveTheFold — everything loaded before scrolling
  • fullPage — cumulative weight after auto-scrolling (strict superset)
  • deferred — derived delta (fullPage − aboveTheFold)

Each phase has total and mutually exclusive byType buckets (html, images, scripts, styles, fonts, video, other) that sum exactly to total.

The phases report weight only. Their emissions are in co2: co2.range.min for aboveTheFold, and co2.perVisit for fullPage.

thirdParty is not in byType — it is an overlapping view. Never add thirdParty.size to a byType sum.

assets — page-level quality signals

Observation only — whether a value is a problem is decided by the issue layer.

SectionKey signals
imagesModern vs legacy formats, lazy/eager, offscreen eager
fontsFormat counts, font-display values, self-hosted vs cross-origin
scripts / stylesMinification verdict and sample size
videoSelf-hosted (measured) vs embedded (estimated)
iframesTotal, lazy, eager

thirdParty

Cross-origin weight as an overlapping view. share is the percentage of full-page total. Per-domain breakdown is opt-in via include: ["thirdPartyDomains"].

"Third party" means a different registrable domain (eTLD+1), not a different hostname.

delivery

Transport and server facts:

  • ttfb — time to first byte
  • redirects — hop count before the final URL
  • protocol — HTTP/3, HTTP/2, etc.
  • compression — document verdict plus textAssets aggregate
  • caching — HTML browser-cache policy, static asset classification

hosting

FieldDescription
green"true" | "false" | "unknown" verdict
providerHosting provider name when known
evidenceUrlLink to green-hosting evidence

issues and issueSummary

issues[] is always present ([] when clean). Each instance:

Issue instance
{
  "id": "image_format",
  "severity": "high",
  "data": { "count": 8 },
  "estimatedSaving": { "value": 735000, "unit": "bytes", "estimated": true }
}

issueSummary provides counts by severity for badge rendering without walking the array.

methodology

Per-scan model inputs:

  • model / version — SWD model identifier
  • basis — emissions basis (fullPage today)
  • scannerVersion — scanner build (cache invalidates on change)
  • grid — per-SWD-segment grid intensity with source and countryCode

warnings

Non-fatal caveats. Always present ([] when clean). Common codes:

CodeMeaning
RESOURCES_CAPPEDHit the 1000-request cap; weight may understate reality
EMBEDDED_VIDEO_ESTIMATEDEmbedded video weight is modelled, not measured
GREENCHECK_UNAVAILABLEGreen-hosting check failed; hosting.green is unknown

Grade bands

Gradeco2.perVisit (gCO2e) ≤
A+0.095
A0.186
B0.341
C0.493
D0.656
E0.846
F> 0.846

On this page