Audit JSON output structure.

// Why this matters

The JSON is the system of record.

Both the in-dashboard audit view and the white-label PDF report are generated from this JSON. Storing the JSON alongside your domain gives you the full audit history in a single source. When the Crawlux REST API ships in Q4 2026, GET /audits/{audit_id} returns the same JSON structure documented here. Building integrations against the JSON shape today means zero migration when the API lands.

// Section 01 // Full output

Top-level shape, every field annotated.

A complete Crawlux audit JSON file. Truncated only where the array length is large (findings can return up to 23 entries for the full analyzer set).

{
  "audit_id": "aud_8f3k29vJ7nQ",
  "version": "v3",
  "domain": "example-protocol.io",
  "tier": "team",
  "started_at": "2026-04-29T08:14:22Z",
  "completed_at": "2026-04-29T08:16:47Z",
  "site_category": "defi_protocol",

  // Overall score and grade
  "score": {
    "overall": 67,
    "grade": "C+",
    "percentile": 58,
    "vertical_percentile": 71
  },

  // Per-check-group breakdown (6 groups, weighted sum = overall)
  "groups": [
    { "id": "technical", "score": 82, "weight": 0.15 },
    { "id": "schema", "score": 45, "weight": 0.20 },
    { "id": "ymyl", "score": 71, "weight": 0.15 },
    { "id": "ai_visibility", "score": 58, "weight": 0.20 },
    { "id": "authority", "score": 76, "weight": 0.15 },
    { "id": "on_chain", "score": 74, "weight": 0.15 }
  ],

  // Findings array — one entry per analyzer that fired
  "findings": [
    {
      "analyzer": "B01",
      "group": "schema",
      "severity": "high",
      "title": "Token page uses generic Product schema",
      "description": "FinancialProduct schema is the correct type for tokens...",
      "recommendation": "Migrate to FinancialProduct schema with crypto fields",
      "reference": "https://www.crawlux.com/guides/token-schema/",
      "affected_pages": ["/token/aave-v3", "/token/aave-v2"],
      "expected_lift": 12
    }
  ],

  // Sources and provenance
  "sources": {
    "dataforseo": "2026-04-29T08:14:24Z",
    "coingecko": "2026-04-29T08:14:31Z",
    "defillama": "2026-04-29T08:14:42Z",
    "pagespeed": "2026-04-29T08:15:08Z"
  }
}

// Section 02 // Field reference

Every top-level field, explained.

audit_id

Unique audit identifier. Format: aud_ followed by 12 alphanumeric characters. Use this to retrieve the audit later via dashboard or, when the API ships in Q4 2026, the GET /audits/{audit_id} endpoint. Immutable across the lifetime of the audit.

version

Methodology version used for this audit. Crawlux methodology is reviewed quarterly. Pinning the version allows reproducible historical audits across version updates. Current version at the time of writing: v3.

domain

The audited domain. Always the apex domain even when the audit started from a subdirectory URL. Subdomains are audited separately and produce distinct audit_id values.

tier

Account tier that triggered the audit. Values: free, pro, team, enterprise. Determines feature surface (webhook callbacks Pro+ only, PDF report Pro+ only).

started_at, completed_at

ISO 8601 timestamps in UTC. Median audit duration is roughly 2.5 minutes; large sites with deep crawls can take up to 8 minutes.

site_category

Auto-detected category. Values: defi_protocol, exchange, wallet, nft_platform, infrastructure, identity, generic_crypto. Determines which AEO prompt set runs and which vertical median benchmarks apply.

score

The overall audit score object. overall is the weighted sum of all 6 groups (0-100). grade is the letter equivalent. percentile is rank across the full Crawlux corpus. vertical_percentile is rank within the detected site_category.

groups

Always 6 entries: technical, schema, ymyl, ai_visibility, authority, on_chain. Weights sum to 1.0.

findings

Array of findings, one per analyzer that flagged an issue. Up to 23 entries. Each finding has analyzer code (A01 through F03), group, severity (low/medium/high), title, description, recommendation, reference URL, affected_pages array, and expected_lift (projected score improvement if remediated).

sources

Provenance object. Records the timestamp each upstream data provider was queried during the audit. Useful for diagnosing stale data.

// Section 03 // Analyzer codes

The 23 analyzer codes by group.

Each finding cites the analyzer code that flagged the issue. Codes are stable across methodology versions; only weights change between versions.

// Section 04 // Working with the output

Common patterns for processing the JSON.

Pattern 1: Sort findings by expected_lift

The fastest path to score improvement is to ship the findings with the highest expected_lift first. Sort the findings array descending by that field and prioritize the top 3 to 5.

const audit = require("./audit-output.json");
const top5 = audit.findings
  .sort((a, b) => b.expected_lift - a.expected_lift)
  .slice(0, 5);
console.log(top5.map(f => `${f.analyzer}: ${f.title} (+${f.expected_lift})`));

Pattern 2: Track score regression over time

Store the JSON for each audit run keyed by completed_at. Compare overall score across runs to detect regressions. A drop of 5+ points usually indicates a deployment broke something measurable.

Pattern 3: Compare against vertical percentile

overall score alone is misleading without context. A 47 in DeFi sits at the median; the same 47 in NFT marketplaces sits in the top quartile. Use vertical_percentile as the meaningful benchmark for category-specific decisions.

// Section 05 // Versioning

How the JSON schema changes between versions.

Methodology versions are reviewed quarterly. Between versions, additive changes are guaranteed safe: new fields may be added but existing fields will not be removed or have their type changed within a major version. Breaking changes require a major version bump (v3 to v4), which has not happened since beta launch.

When parsing the JSON, code defensively. Treat unknown fields as forward-compatible. Do not assume the findings array has a fixed length. Always check that nested objects exist before reading their fields.

// Related docs

Where to go from here.

• Webhooks documentation — receive the audit JSON via POST when audits complete
• REST API reference — Q4 2026 endpoint surface for retrieving audits programmatically
• Methodology documentation — full analyzer references with calibration sources