How to Run a Deep Audit: The Complete Guide

Deep Audit is an AI-assisted, 9-dimension site audit — the one built for the AI-search era and delivered as an API you can automate, not a dashboard you log into. This guide takes you from zero to a scored report, in whatever tool you work in — cURL, Python, Node, n8n, or an AI agent — and shows you how to read the results and wire them into CI/CD.

• Base URL: https://engine.seoscoreapi.com
• Interactive API docs: https://engine.seoscoreapi.com/docs
• Plan required: Pro or Ultra

1. Prerequisites

You need a Pro or Ultra API key (Deep Audit is the heavy, AI-backed analysis, so it's a paid feature). Your existing SEO Score API key works — send it as the X-API-Key header.

Check your remaining quota anytime:

curl https://engine.seoscoreapi.com/usage -H "X-API-Key: $KEY"
# {"tier":"ultra","site_audit":{"used":3,"remaining":97}, ...}

2. The 60-second quickstart

The SDKs wrap the whole submit-and-wait flow in a single call:

Python

pip install seoscoreapi

import seoscoreapi as seo
result = seo.deep_audit("https://yoursite.com", "YOUR_KEY", business_type="saas")
print(result["scores"]["lai_score"], result["scores"]["lai_grade"])

Node

npm install seoscoreapi

const seo = require("seoscoreapi");
const result = await seo.deepAudit("https://yoursite.com", "YOUR_KEY", { business_type: "saas" });
console.log(result.scores.lai_score, result.scores.lai_grade);

That's it. Everything below is for when you want more control.

3. How the async flow works

A Deep Audit renders the page in a real browser, runs thousands of checks, and does an AI analysis pass — so it takes ~1–2 minutes. It runs as a background job:

1. Submit → get a job_id instantly.
2. Poll the job until it's completed.

# 1) Submit
curl -X POST https://engine.seoscoreapi.com/site-audit \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.com"}'
# → {"job_id":"a1b2c3","status":"queued","poll":"/site-audit/a1b2c3"}

# 2) Poll
curl https://engine.seoscoreapi.com/site-audit/a1b2c3 -H "X-API-Key: $KEY"

The poll response tells you where things stand:

Doing it by hand? Poll every ~5 seconds. Respect these signals:

• On submit, a 429 means either your monthly quota is used up or the queue is full (a burst-protection measure). Check the Retry-After header and retry later. No quota is consumed on a queue-full 429.
• Prefer not to poll at all? Pass a webhook_url and we'll POST the finished job to it.

4. Submit options

POST /site-audit accepts:

Why business_type matters: the engine won't score a SaaS homepage against Event, Product, or Recipe schema, or a blog against e-commerce checks. Setting it avoids misleading "critical" findings for things that don't apply to you.

5. Reading the result

A completed audit's result looks like this:

{
  "website_url": "https://yoursite.com",
  "scores": {
    "lai_score": 3.87, "lai_grade": "good",   // headline, 0–5
    "ai_score": 3.75,                          // AI-readability
    "seo_score": 2.70,                         // classic on-page SEO
    "section_scores": { "1": 4.31, "2": 4.76, "...": "...", "9": 3.04 }
  },
  "sections": [ { "name": "Technical Foundation & Rendering", "score": 4.31 }, ... ],
  "findings": [
    { "task_id": "7.5.02", "section": 7, "severity": "high",
      "weight": "critical", "evidence": "No CSP", "count": 3 }, ...
  ],
  "coverage": {
    "scored_tasks": 6022, "not_applicable_tasks": 330,
    "hybrid_ai_tasks": 150, "coverage_pct": 41.9
  }
}

How to read it:

• lai_score (0–5) is your headline. ai_score and seo_score split it into "how well AI can read you" vs "classic SEO."
• section_scores (1–9) show where you're strong and weak. The nine sections: 1 Technical Foundation · 2 Crawlability · 3 Content & Entity Semantics · 4 Core Web Vitals · 5 Technical SEO · 6 Schema/Trust · 7 Security · 8 Media · 9 Off-Site.
• findings are your to-do list, each with a plain-English evidence string, a severity (high/…), and a weight (critical/heavy/medium). Start with weight: critical + severity: high.
• coverage is your honesty check: how many tasks were scored, how many were not_applicable (correctly skipped for your business type), and how many hybrid_ai_tasks the AI evaluated.

Fixing the common ones: missing schema → add the relevant JSON-LD (Organization, Service, FAQPage, etc.); No CSP / missing security headers → set them at your app or CDN; thin content → deepen the page and tighten entity coverage. Re-audit to confirm the lift.

6. Use it in your workflow

CI/CD quality gate (synchronous)

Fail a build when SEO regresses — gate-scan runs synchronously and returns pass/fail:

curl -X POST https://engine.seoscoreapi.com/gate-scan \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://staging.yoursite.com","min_score":3.5}'
# → {"passed":true,"score":3.87,"blockers":[...]}

passed is false if the score is below min_score or there are high-severity blockers — wire that into your pipeline's exit code.

n8n (no-code)

Install n8n-nodes-seoscoreapi, add the SEO Score API node, pick the Deep Audit operation, set the URL (and optionally Business Type). The node submits and waits, returning the full result to the next step. Great for "schedule → Deep Audit → if score drops → Slack."

AI agents (MCP)

Add the MCP server so Claude, Cursor, or any MCP client can run audits as a tool:

{
  "mcpServers": {
    "seoscoreapi": {
      "command": "npx",
      "args": ["-y", "seoscoreapi-mcp"],
      "env": { "SEO_SCORE_API_KEY": "YOUR_KEY" }
    }
  }
}

Then just ask: "Run a deep audit on example.com and summarize the top fixes." The deep_audit tool submits, waits, and returns the report.

Webhooks

Pass webhook_url on submit and skip polling entirely — you'll get a POST with the finished job when it completes.

7. Beyond the audit

Your key also unlocks:

• POST /serp/search — live SERP results + your ranking for a query
• POST /serp/compare — head-to-head SERP gap analysis vs competitors
• POST /engine-radar — how AI answer engines describe your brand
• GET /catalog — browse every check the engine runs (no key needed)

(SERP endpoints draw on your monthly SERP quota.)

8. Errors & limits

• Rate limit: default 60 requests/min per key.
• Quota: Deep Audits are metered monthly by plan (see §1). A queue-full 429 does not consume quota.
• Timeouts: audits typically finish in 1–2 minutes; the SDK helpers wait up to 10 minutes by default and handle backpressure for you.

Full reference

Interactive, always-current API docs: https://engine.seoscoreapi.com/docs