Scoring & History Tracking

/v1/seo/audit (and the bulk/compare variants) return a score between 0 and 100. That number is a heuristic — useful for dashboards and trend lines, dangerous as a hard gate. This page documents exactly how it's computed so you can decide which checks to enforce individually, plus how to snapshot audits over time and diff them.

If you only want the raw audit fields, see SEO Audit. For multi-URL runs, see Bulk Audit and Compare.

How the score is computed

Every check contributes a fixed weight; the total is capped at 100. There are no penalties and no negative points.

Check Points Awarded when
Meta title 15 Present and 30–60 characters
Meta title (partial) 8 Present but length outside 30–60
Meta description 15 Present and 120–160 characters
Meta description (partial) 8 Present but length outside 120–160
Open Graph 10 3 points each for og:title, og:description, og:image (capped at 10)
Twitter Card 5 twitter:card present
H1 10 Exactly one <h1>
H1 (partial) 5 More than one <h1>
Image alt text 10 Every <img> has non-empty alt — or the page has zero images
Image alt (partial) 0–9 floor(with_alt / total * 10) when some are missing
Canonical 5 <link rel="canonical"> present
Robots meta 5 robots_meta does not contain noindex (including when absent)
lang attribute 5 <html lang="..."> present
Viewport 10 <meta name="viewport"> present

Things worth noticing:

  • Viewport and both meta tags carry the most weight (15 + 15 + 10 = 40 points). A page failing those three can still reach ~60, which is why a score in the 60s usually isn't a crisis.
  • noindex costs only 5 points. A page with noindex can score 95. Never treat the score as an indexability check — read robots_meta directly.
  • Zero images scores full marks. A text-only page isn't penalised for having no alt text.
  • Multiple H1s still earn 5 of 10. Don't expect the score to fall off a cliff for a duplicate H1.
  • Heading hierarchy length is not scored. heading_hierarchy is informative only.

Using the score responsibly

# Good: gate on discrete facts
assert audit["meta_title"]["present"], "no title"
assert audit["headings"]["h1"] == 1, f"{audit['headings']['h1']} H1 tags"
assert audit["canonical"], "no canonical"
assert "noindex" not in (audit["robots_meta"] or "").lower(), "page is noindex"

# Fine: gate on a trend, not a single snapshot
if audit["score"] < baseline_score - 10:
    print(f"Score dropped {baseline_score} → {audit['score']}")

Reconstructing the score client-side

If you only stored the compact bulk result, you can't recompute the score exactly (og/twitter/lang/canonical details are collapsed). Store the full /v1/seo/audit payload, or store the bulk flags alongside the score so a future scoring change is detectable.

Snapshotting audits over time

The API is stateless: nothing is retained between calls. Trend tracking is your job. The simplest durable pattern is one JSON document per URL per day:

import json, pathlib, requests, datetime

def snapshot(url: str, root="seo-history"):
    audit = requests.get(
        "https://seo.toolkitapi.io/v1/seo/audit",
        params={"url": url},
        headers={"x-api-key": API_KEY},
        timeout=30,
    ).json()

    day = datetime.date.today().isoformat()
    path = pathlib.Path(root) / day / f"{hash(url) & 0xffffffff:08x}.json"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(json.dumps(audit, indent=2))
    return audit

Then diff two snapshots to answer "what changed?":

def diff(prev: dict, curr: dict) -> list[str]:
    out = []
    if prev["score"] != curr["score"]:
        out.append(f"score {prev['score']} → {curr['score']}")
    for tag in ("meta_title", "meta_description"):
        p, c = prev[tag], curr[tag]
        if p["value"] != c["value"]:
            out.append(f"{tag} changed ({p['length']} → {c['length']} chars)")
    if prev["headings"] != curr["headings"]:
        out.append(f"headings {prev['headings']} → {curr['headings']}")
    if prev["images"]["without_alt"] != curr["images"]["without_alt"]:
        out.append(
            f"missing alt {prev['images']['without_alt']} → {curr['images']['without_alt']}"
        )
    if bool(prev["canonical"]) != bool(curr["canonical"]):
        out.append("canonical added/removed")
    return out

For a whole site, loop over /v1/seo/bulk-audit in chunks of 10 — the bulk response already carries score, has_h1, has_viewport, images_without_alt, and error per URL, which is enough for a dashboard line.

Alerting checklist

Alert on Field Suggested threshold
Page went noindex robots_meta contains noindex
Canonical disappeared canonical null where it previously had a value
Title/description truncated or empty meta_title.length / meta_description.length outside 30–60 / 120–160
Alt-text regression images.without_alt increased vs. previous snapshot
H1 count drift headings.h1 != 1
Aggregated regression score drop > 10 vs. 7-day baseline

Errors

Same as /v1/seo/audit: 400 for malformed or SSRF-blocked URLs, 401 for auth, 422 for a missing url query param, 502 when the target can't be fetched.

See also

  • SEO Audit — full field-by-field response reference
  • Bulk Audit — up to 10 URLs per request
  • Compare — side-by-side metrics for 2–5 pages
  • Page Speed — TTFB, size and compression signals