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.
noindexcosts only 5 points. A page withnoindexcan score 95. Never treat the score as an indexability check — readrobots_metadirectly.- 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_hierarchyis 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