Carbon.txt Auditor

Discover and audit a public domain's carbon.txt sustainability disclosure file against the Green Web Foundation carbon.txt v0.5 syntax. Carbon.txt is the emerging standard for publishing machine-readable sustainability data disclosures (carbon footprint, energy mix, CSRD reports, AI model cards) at a predictable location on a domain.

Use cases

• Sustainability and ESG teams verifying their own carbon.txt deployment before a public announcement.
• Compliance and legal teams auditing CSRD-related disclosure publication readiness.
• Agencies and consultants running carbon.txt audits across a client portfolio.
• Procurement and investor-research teams checking whether a vendor or portfolio company publishes verifiable sustainability disclosures.
• CI/CD pipelines validating a carbon.txt file after edits, before deployment.

Input

Field	Type	Required	Description
startUrl	string	yes	Domain or URL to audit, e.g. example.com or https://example.com.
checkDisclosureUrls	boolean	no	If true, performs a reachability check (HEAD, falling back to a capped GET) against each disclosure URL found in the file. Default false.
timeoutSeconds	integer	no	Per-request timeout, 3-30 seconds. Default 10.

Output

One JSON object per run, pushed to the default dataset.

Field	Type	Description
inputDomain	string	The domain/URL provided as input.
discoveryMethod	string	How the file was located: dns-txt, root, well-known, header, or none.
carbonTxtUrl	string|null	URL the carbon.txt file was fetched from, if found.
https	boolean|null	Whether it was served over HTTPS.
status	integer|null	Final HTTP status code.
fileFound	boolean	Whether any discovery method succeeded.
tomlValid	boolean	Whether the body parses as valid TOML.
parseError	string|null	TOML parse error message, if any.
version	string|null	Declared version field.
lastUpdated	string|null	Declared last_updated field.
hasOrgSection	boolean	Whether a required [org] table is present.
disclosureCount	integer	Number of org.disclosures entries.
disclosures	array	Parsed disclosure entries: docType, url, validUntil, domain, title, issues.
hasUpstreamSection	boolean	Whether an optional [upstream] table is present.
upstreamServiceCount	integer	Number of upstream.services entries.
upstreamServices	array	Parsed service entries: domain, serviceType, issues.
disclosureUrlChecks	array|null	Per-URL reachability results, if checkDisclosureUrls was enabled.
checks	array	Per-check breakdown: name, status, note, weight, recommendation.
issues	array	Deduplicated list of all issues found.
score	integer	Readiness score, 0-100.
grade	string	Letter grade, A+ to F.
checkedAt	string	ISO timestamp of the audit.
recommendations	array	Actionable fixes.
error	string|null	Top-level fetch error, if any.

Example input

{
  "startUrl": "https://example.com",
  "checkDisclosureUrls": true,
  "timeoutSeconds": 10
}

Example output (abridged)

{
  "inputDomain": "https://example.com",
  "discoveryMethod": "root",
  "carbonTxtUrl": "https://example.com/carbon.txt",
  "https": true,
  "status": 200,
  "fileFound": true,
  "tomlValid": true,
  "version": "0.5",
  "hasOrgSection": true,
  "disclosureCount": 1,
  "disclosures": [
    { "index": 0, "docType": "sustainability-page", "url": "https://example.com/sustainability", "validUntil": null, "domain": "example.com", "title": null, "issues": [] }
  ],
  "hasUpstreamSection": false,
  "upstreamServiceCount": 0,
  "upstreamServices": [],
  "score": 90,
  "grade": "A",
  "issues": [],
  "recommendations": ["carbon.txt looks spec-conformant. Re-run this audit after updating sustainability disclosures to catch regressions."]
}

Discovery method

Per the carbon.txt FAQ, discoverability is checked in this order:

1. DNS TXT record on the domain in the form carbon-txt-location=URL.
2. https://<domain>/carbon.txt (domain root).
3. https://<domain>/.well-known/carbon.txt.
4. A CarbonTxt-Location: URL HTTP response header on the domain root.

The actor stops at the first location that returns a 200 response and attempts to parse it as TOML.

Security

• Public HTTP/HTTPS only. URL credentials are rejected.
• Localhost and private/link-local IPv4 and IPv6 literal ranges (RFC 1918, RFC 3927, and IPv6 unique-local/link-local equivalents) are blocked.
• Hostnames are DNS-resolved and resolved addresses are re-checked against the same private-range rules before any request is made (SSRF defense in depth).
• Redirects are manually followed and each hop is revalidated with the same SSRF checks.
• Response bodies are capped at 256 KB.
• Only the exact disclosure URLs found inside the carbon.txt file are fetched when checkDisclosureUrls is enabled; no other URLs referenced by the file are followed.

Pricing

Event	Price (USD)
Actor start	$0.005
Domain audited	$0.01

Apify takes a 20% platform commission; the operator keeps 80%.

FAQ

What is carbon.txt? An open specification from the Green Web Foundation for publishing machine-readable sustainability disclosure links (carbon footprint reports, energy mix data, CSRD reports, AI model cards) at a predictable location on a web domain.

Does this actor validate the disclosure document contents? No. It validates the carbon.txt file's structure and, optionally, that each linked disclosure URL is reachable. It does not parse PDF annual reports or verify the sustainability claims themselves.

Does it support older carbon.txt syntax versions (pre-0.3)? The actor validates against the current v0.5 TOML structure ([org].disclosures, [upstream].services). Older array-of-tables syntax from early drafts is not retro-validated.

Why didn't it find my carbon.txt file? Check that it is reachable at the domain root, /.well-known/, via a carbon-txt-location= DNS TXT record, or via a CarbonTxt-Location HTTP header, and that it responds with HTTP 200 over HTTPS.