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
| Field | Description |
|---|---|
version | Contract version ("2.0"). Not the scanner version — see methodology.scannerVersion. |
scanId | Opaque identifier. Never parse it. |
status | "completed" in sync mode. "pending" and "failed" reserved for future async support. |
cached | true when served from our scan-result cache (not the target site's CDN cache). |
url | Final URL after redirects. |
website | Hostname (e.g. blog.example.com). Subdomains are tracked separately. |
scannedAt | ISO-8601 timestamp of when the measurement ran. |
grade | A+ through F, derived from co2.perVisit. |
co2 — headline emissions
| Field | Description |
|---|---|
perVisit | Canonical emissions for one visit. Drives grade. |
perByte | Emissions per transferred byte under the same grid assumptions. |
range.min | Above-the-fold emissions — floor for visitors who never scroll. |
range.max | Full-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 scrollingfullPage— 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.
| Section | Key signals |
|---|---|
images | Modern vs legacy formats, lazy/eager, offscreen eager |
fonts | Format counts, font-display values, self-hosted vs cross-origin |
scripts / styles | Minification verdict and sample size |
video | Self-hosted (measured) vs embedded (estimated) |
iframes | Total, 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 byteredirects— hop count before the final URLprotocol—HTTP/3,HTTP/2, etc.compression— document verdict plustextAssetsaggregatecaching— HTML browser-cache policy, static asset classification
hosting
| Field | Description |
|---|---|
green | "true" | "false" | "unknown" verdict |
provider | Hosting provider name when known |
evidenceUrl | Link to green-hosting evidence |
issues and issueSummary
issues[] is always present ([] when clean). Each 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 identifierbasis— emissions basis (fullPagetoday)scannerVersion— scanner build (cache invalidates on change)grid— per-SWD-segment grid intensity withsourceandcountryCode
warnings
Non-fatal caveats. Always present ([] when clean). Common codes:
| Code | Meaning |
|---|---|
RESOURCES_CAPPED | Hit the 1000-request cap; weight may understate reality |
EMBEDDED_VIDEO_ESTIMATED | Embedded video weight is modelled, not measured |
GREENCHECK_UNAVAILABLE | Green-hosting check failed; hosting.green is unknown |
Grade bands
| Grade | co2.perVisit (gCO2e) ≤ |
|---|---|
| A+ | 0.095 |
| A | 0.186 |
| B | 0.341 |
| C | 0.493 |
| D | 0.656 |
| E | 0.846 |
| F | > 0.846 |
Related
- Conventions —
Measure, verdicts, rounding - Issues & recommendations
- API reference