API reference

Quickstart

Create a key, start a scan, poll until it completes, read the numbers:

# 1. Start a scan
curl -X POST https://carbonless.cc/api/v1/scans \
  -H "Authorization: Bearer $CARBONLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com/pricing"}'
# => { "scanId": "9f1c..." }

# 2. Poll until status is "complete" (a few seconds apart)
curl https://carbonless.cc/api/v1/scans/9f1c...
# => { "status": "complete", "rating": "B", "co2": { "perVisit": 0.140, ... }, ... }

The same flow in JavaScript:

const started = await fetch('https://carbonless.cc/api/v1/scans', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.CARBONLESS_KEY}`,
    'content-type': 'application/json'
  },
  body: JSON.stringify({ url: 'example.com/pricing' })
}).then((r) => r.json());

let scan;
do {
  await new Promise((r) => setTimeout(r, 3000));
  scan = await fetch(`https://carbonless.cc/api/v1/scans/${started.scanId}`).then((r) => r.json());
} while (scan.status === 'queued' || scan.status === 'running');

console.log(scan.rating, scan.co2.perVisit, 'g CO2e per visit');

Carbon budgets in CI

The GitHub Action wraps this API into a build check: it measures a page and fails the build when your budget is exceeded. Store the key as a repository secret named CARBONLESS_API_KEY.

- uses: stfurkan/carbonless-action@v1
  with:
    url: ${{ steps.deploy.outputs.preview-url }}
    api-key: ${{ secrets.CARBONLESS_API_KEY }}
    max-co2: "0.25"      # grams CO2e per visit
    max-bytes: "1500000" # optional page weight budget

• The scanner measures from the public internet, so point it at a URL it can reach. The strongest setup is your platform's preview deployment (Vercel, Netlify, Cloudflare Pages give every pull request a public URL), which checks exactly the code in the PR before anything reaches production. A public staging URL works the same way.
• Password-protected previews and intranet URLs cannot be measured: the crawler identifies itself and does not evade access controls.
• Preview URLs are unique per deployment, so every run is a fresh measurement. Production URLs re-measure at most once a day, like everywhere else.

Authentication

Send your key as a bearer token. Starting a scan always needs a key; requests without a valid one get a 401. Reading a scan needs no key, because every result is public.

Authorization: Bearer cbl_your_key_here

• Keys are created and revoked under /keys. The plaintext is shown once at creation and never again; revocation takes effect on the next request.
• A key is a headless sign-in: it spends the same per-account quota as using the site signed in, so it is not a way around the limits.
• Keys belong on your server. Do not embed one in a browser or mobile app; anyone who can read it can spend your quota.
• X-API-Key: cbl_... is accepted as an alternative header where setting Authorization is awkward.

Versioning

The version lives in the path: /api/v1. Within v1, changes are additive only: new fields may appear in responses, and existing fields keep their name, type and meaning. Anything that would change the meaning of a number you already store, such as a new emissions model or revised rating boundaries, ships as a new version path with the old one kept running and a deprecation timeline announced here.

• Each result carries co2.model (currently "swdm-v4"), so stored figures stay attributable to the model that produced them.

The scan lifecycle

A scan moves through queued → running → either complete or failed. A real browser loads the page twice (cold, then warm to measure caching), so a typical scan finishes in under a minute.

• Pages re-measure at most once a day. Submitting a URL measured within the last day returns the existing result immediately with "fresh": true, costs no quota, and there is no force flag: polling in a loop costs nothing and changes nothing.
• Submitting a URL that is already queued or running attaches you to the in-flight scan instead of starting a second one.
• failed is a real outcome, not an HTTP error: the response is still 200 with error explaining why, most often a site that refuses automated visits. Failed scans of that kind are not retried; re-driving a site that said no only annoys it.
• Redirects are followed and the result is filed under the final URL, reported in measuredUrl.

Errors

Errors use conventional status codes and a JSON body with a human-readable error string plus a stable machine-readable code. Branch on the code, never on the prose: messages can be reworded, codes keep their meaning (new ones may be added).

{ "error": "That API key is not valid or has been revoked.", "code": "api_key_invalid" }

Every response carries an x-request-id header (yours is echoed back if you send a simple one). Quote it when reporting a problem and we can find the exact request in our logs.

Rate limits

• Scan submissions draw from an hourly per-account quota plus a short burst guard, shared between your keys and signed-in use of the site. Limits are generous for comparing a handful of sites and are tuned during the beta.
• Responses served from the freshness window ("fresh": true) do not count against the quota.
• On 429, wait the seconds given in retry-after and retry. Spreading bulk work out is kinder than hammering the hour boundary.
• Reading scans has a generous per-address flood cap (well above any reasonable polling rate); a tight loop gets a 429 with the same retry-after handling.

Start a scan

POST/api/v1/scans

Queues a measurement of one page, or returns the recent existing result. Requires a key.

Request body

Returns

Example

curl -X POST https://carbonless.cc/api/v1/scans \
  -H "Authorization: Bearer $CARBONLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com/pricing"}'

# 202 (queued)
{ "scanId": "9f1c..." }

# 200 (measured within the last day)
{ "scanId": "9f1c...", "fresh": true, "reportPath": "/report/example.com/pricing" }

Every scan is public: submitting a URL publishes a report page for it. Do not scan pages you would not want listed.

Read a scan

GET/api/v1/scans/{id}

Returns the scan object. No authentication: everything here is already on the public report page, and polling this endpoint is how a client waits for a scan it started. Poll every few seconds, not in a tight loop.

Example

curl https://carbonless.cc/api/v1/scans/9f1c...

{
  "id": "9f1c...",
  "status": "complete",
  "error": null,
  "url": "https://example.com/pricing",
  "measuredUrl": "https://example.com/pricing",
  "measuredAt": "2026-08-08T09:41:22.000Z",
  "rating": "B",
  "co2": {
    "perVisit": 0.140,
    "firstVisit": 0.185,
    "returnVisit": 0.008,
    "unit": "grams CO2e",
    "model": "swdm-v4"
  },
  "transfer": {
    "bytes": 1245328,
    "warmBytes": 53210,
    "requests": 48,
    "thirdPartyBytes": 402118,
    "thirdPartyRequests": 12,
    "domains": 7
  },
  "performance": { "ttfbMs": 210, "fcpMs": 890, "lcpMs": 1320, "cls": 0.01, "loadMs": 1900, "domElements": 812 },
  "greenHost": false,
  "cleanerThanPercent": 80.8,
  "reportUrl": "https://carbonless.cc/report/example.com/pricing",
  "reportPath": "/report/example.com/pricing"
}

The scan object

While a scan is queued or running, only id, status, error and url are present, plus reportPath: null. The full object appears once status is complete.

Figures are estimates from a published model applied to a real measurement. The methodology states every assumption.