DEV Community: Aaron VanSledright

SEO Monitor API: Score Tracking with Webhooks and Slack Alerts

Aaron VanSledright — Mon, 26 Oct 2026 14:00:02 +0000

SEO monitoring is the practice of automatically auditing a URL on a recurring schedule and alerting you when the score changes significantly. Without monitoring, a broken meta tag, a removed H1, or a slow server after a deploy can sit undetected for days — long enough for Google to notice and adjust your rankings.

SEO Score API is a REST API that monitors any URL every 6 hours and emails you when the score drops or rises by 5+ points, giving you a real-time quality gate on your site's SEO health.

Why Does SEO Monitoring Matter?

SEO monitoring matters because SEO problems are almost always introduced by changes — deploys, CMS updates, plugin installs, or CDN configuration changes. Common scenarios that monitoring catches:

A developer deploys a new page template that strips the meta description
A CMS update removes the canonical tag site-wide
A CDN misconfiguration causes pages to load in 4+ seconds
An OG image URL breaks after a media library migration

Each of these would lower your SEO score by 10–30 points within hours. With monitoring, you know the same day it happens.

How Does SEO Score Monitoring Work?

SEO Score monitoring works by storing the URLs you want to watch, auditing each one automatically every 6 hours, comparing the new score to the previous score, and sending an email alert if the difference is 5 or more points.

The full cycle:

You register a URL via POST /monitors
The API audits it immediately to establish a baseline score
Every 6 hours, the API re-audits the URL
If the score changes by ±5 points, you receive an email with the delta and a list of what changed

How Do You Set Up SEO Monitoring?

You set up SEO monitoring by making a POST request to the monitors endpoint with your URL and API key.

curl -X POST https://seoscoreapi.com/monitors \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com"}'

from seoscoreapi import add_monitor

result = add_monitor("https://yoursite.com", api_key="your_key")
print(f"Monitoring started. Baseline score: {result['score']}")

List your active monitors:

curl https://seoscoreapi.com/monitors \
  -H "X-API-Key: your_api_key"

What Triggers a Monitoring Alert?

A monitoring alert is triggered when the score for a monitored URL changes by 5 or more points between audit cycles. Alerts fire for both drops and improvements.

The alert email includes:

The URL that changed
The previous score and new score
The point delta (e.g., −18 points)
A list of checks that changed status since the last audit

How Many URLs Can You Monitor Per Plan?

Plan	Price	Monitored URLs
Starter	$5/mo	5 URLs
Basic	$15/mo	10 URLs
Pro	$39/mo	25 URLs
Ultra	$99/mo	50 URLs

Monitoring is not available on the free tier.

Which URLs Should You Monitor?

You should monitor your highest-value URLs first — pages that drive traffic, generate leads, or support paid campaigns. Recommended starting points:

Homepage — highest-authority page, most vulnerable to template changes
Top 5 organic traffic pages — most likely to affect revenue if rankings drop
Product or service landing pages — especially if you run paid search to them
Any page recently launched or redesigned

How Is SEO Monitoring Different from Google Search Console?

SEO monitoring via API is different from Google Search Console in timing and scope. Search Console reports what Google has already indexed — it reflects the past. Score monitoring catches problems in real time, before Google re-crawls the affected page.

Key differences:

Timing: API monitoring alerts within 6 hours; Search Console data lags 1–7 days
Scope: API monitoring checks 54+ technical factors; Search Console focuses on crawl errors and search performance
Action: API monitoring tells you exactly which check failed; Search Console tells you traffic dropped

Frequently Asked Questions

How often does SEO monitoring run?

SEO monitoring audits each registered URL every 6 hours. You will receive an alert within 6 hours of a score-changing event, such as a deploy that removes a meta tag or a server slowdown that degrades your performance score.

What plan do I need for SEO monitoring?

SEO monitoring requires a paid plan. The Starter plan ($5/month) includes 5 monitored URLs. Basic ($15/month) includes 10, Pro ($39/month) includes 25, and Ultra ($99/month) includes 50. The free tier does not include monitoring.

Can I monitor competitor websites?

Yes. The API monitors any publicly accessible URL, including competitor pages. Monitoring a competitor's key landing pages can alert you when they make significant SEO changes.

What happens if a monitored URL goes down?

If a monitored URL returns a 4xx or 5xx error, the audit records a failed response. A server error or 404 will cause a significant score drop and trigger an alert. The alert email will note the response code so you can distinguish an SEO regression from an availability issue.

Does monitoring count against my audit quota?

Yes, each scheduled monitoring audit counts against your monthly audit quota. On the Starter plan with 5 monitors, the system runs approximately 600 monitoring audits per month. Plan your monitor count relative to your monthly quota.

What Is a Good SEO Score? 70+, and What Grades A–F Mean

Aaron VanSledright — Mon, 19 Oct 2026 14:00:05 +0000

An SEO score is a number from 0 to 100 that measures how well a single page is set up for search engines: its meta tags, technical setup, performance, social tags, and basic accessibility. A good SEO score is 70 or above, which is a B grade. Across the audits we have run, though, the average page already scores about 73, so 70 is closer to "normal" than "ahead". The score that separates a page from the pack is 80.

SEO Score API is a REST API that runs 80+ automated checks on a URL and returns one composite score with a letter grade, so developers and agencies can measure and track SEO health in code. The score and the SEO grade bands below are the ones that API returns.

What Does an SEO Score Measure?

An SEO score measures the technical and on-page health of one URL across five weighted categories. Each category returns its own sub-score, so you can see which area is pulling the total down. Meta and technical count for most of the score; social and accessibility count for the least.

The five categories are:

Meta and content: title tag, meta description, H1 and heading order, content length, readability, internal and external links
Technical: HTTPS and the SSL certificate, status code, response time, canonical tag, viewport, robots meta, robots.txt, sitemap, structured data
Performance: HTML size, DOM size, compression, render-blocking CSS and scripts
Social: Open Graph tags, Twitter Card tags, favicon
Accessibility: the lang attribute, alt text coverage on images, landmark elements

It does not measure backlinks, keyword rankings, domain authority, or whether the content is any good. Those decide a lot of where a page ranks, and no on-page score sees them.

The accessibility category is a lightweight check within the SEO score. If you need a full legal-grade audit, our dedicated ADA compliance checker runs the complete WCAG 2.1 AA ruleset (via axe-core) and returns an accessibility score plus a lawsuit-risk assessment.

What Is a Good SEO Score?

A good SEO score is 70 or above. A score of 80 or higher is great, and 90 or higher is excellent.

That is the grading answer. The practical answer comes from the data. In roughly 8,000 audits run through the API, the average score was about 73, about 90% of audits landed between 70 and 79, and about 8% reached 80 or higher. Almost nothing scored below 60. (The numbers and their caveats are in what we're seeing after 8,000 audits; the sample is pages somebody chose to audit, not a random crawl of the web.)

So a 73 means the basics are in place and the page has the same handful of gaps as nearly every other page. An 80 means you have closed them.

SEO Grades: What A+ Through F Mean

An SEO grade is the letter attached to the score. The bands are fixed:

SEO Grade	Score Range	What It Means
A+	90–100	Excellent. Every category is in good shape
A	80–89	Great. Ahead of about nine in ten audited pages
B	70–79	Good, and the most common grade by far
C	60–69	Below average. Usually one category is failing
D	50–59	Poor. Several basics are missing
F	0–49	Failing. Something is blocking the page outright

Two things are worth knowing about how the grade is worked out. It comes from the weighted total, not from an average of the category grades, so a page can earn an A overall with a weak social score. And a grade says how many known problems the page has, not how it will rank: an A+ page with no links and nothing useful on it still will not rank.

Is 75 a Good SEO Score?

Yes, 75 is a good SEO score. It sits in the B band (70–79) and a little above the average of 73 in our audits. It is not holding the page back. The quickest gains from there come from whichever category has the lowest sub-score, which is the social category more often than any other.

Good SEO Scores by Number: 60, 70, 80, 85, 90

Here is a quick answer for the exact scores people ask about most:

Is 60 a good SEO score? No. 60 is the bottom of the C band (60–69) and well below the pages we usually see; very few audits score that low. It normally means a whole category is failing, most often missing meta tags or no HTTPS. It is fixable in an afternoon.
Is 70 a good SEO score? Yes. 70 is the start of the B band and the pass mark. It is also slightly below average, so treat it as a floor.
Is 80 a good SEO score? Yes. 80 earns an A, and only about 8% of the audits we run reach it. It is the target we would set for most pages.
Is 85 a good SEO score? Yes. 85 is a strong A. Past this point each extra point costs more work and buys less.
Is 90 a good SEO score? Yes. 90 and above is an A+, and it is rare.
Is 100 a good SEO score? It is a perfect one, and it is not worth chasing. See the FAQ below.

Not sure where your page lands? Check any URL's SEO score for free. No credit card required.

What Score Do You Need to Rank on Google?

There is no score that gets a page ranked. Google does not use this score or anybody else's; an SEO score is a third-party checklist, and Google has no "SEO score" of its own. Pages with a 72 outrank pages with a 95 every day, because links, relevance, and content quality are not in the number.

What the score tells you is whether something on the page is getting in the way: a noindex left on by accident, a missing canonical, no HTTPS, a title Google has to rewrite. Those are worth fixing whatever the page is trying to rank for.

Our view: get to 80, then stop working on the score and work on the content and the links. Going from 85 to 95 is usually wasted effort.

How Do You Check Your SEO Score?

You can check your SEO score with the SEO Score API by making a single GET request. The API returns a full JSON audit in seconds, including your composite score, letter grade, and per-category breakdowns.

curl "https://seoscoreapi.com/audit?url=https://yoursite.com" \
  -H "X-API-Key: your_api_key"

The response includes:

{
  "url": "https://yoursite.com",
  "score": 82,
  "grade": "A",
  "audit": {
    "meta": { "score": 90 },
    "technical": { "score": 78 },
    "performance": { "score": 74 },
    "social": { "score": 85 },
    "accessibility": { "score": 80 }
  }
}

Sign up for a free API key at seoscoreapi.com. No credit card is needed. The free tier is 2 audits per day and returns the score, the grade, 2 checks per category, and the top 2 priorities; paid plans return every check.

What Causes a Low SEO Score?

A low SEO score is caused by missing on-page elements or a broken technical setup. Five issues turn up among the top priorities on roughly nine out of ten audits we run:

No structured data (JSON-LD)
No sitemap.xml
No meta description
No canonical tag
Thin content on the audited page

Those five are why so many pages sit at 73. The issues that drag a page lower than that are less common and more serious:

Missing or empty title tag
No H1
HTTP instead of HTTPS, or a broken SSL certificate
No viewport tag, so the page is not mobile-friendly
A server response slower than a second

Performance is rarely the problem. The performance category averages about 97 out of 100 in our audits, while the social category averages about 41, mostly from missing og:image and Twitter Card tags.

The audit response includes a priorities array listing the failed checks in order, with what to fix for each.

How Do You Improve Your SEO Score?

You improve your SEO score by fixing the specific issues flagged in your audit report, starting with the highest-impact failures. The fastest wins are usually:

Add a meta description. It is not a ranking factor, but it is what searchers read before they click, and it is missing on most pages we audit.
Add a canonical tag. One line in the <head>, and it stops duplicate URLs competing with each other.
Add structured data. An Organization, Article, or Product JSON-LD block that matches the page.
Publish a sitemap.xml and reference it from robots.txt.
Complete the Open Graph and Twitter Card tags, including og:image. This is where the social sub-score is usually lost.
Fix the title tag. Aim for 50–60 characters, unique per page.

After fixing them, audit the same URL again to confirm the score moved. Teams that run the API in CI/CD catch regressions the same way: a deploy that drops the meta description fails the check before it reaches production.

How Often Should You Audit Your SEO Score?

You should audit your SEO score whenever you deploy changes to a page, and run scheduled audits at least weekly for important URLs. Score drops of 5+ points usually indicate a broken element introduced by a recent change: a template update, CMS migration, or plugin conflict.

On paid plans, score monitoring re-audits a URL daily or weekly and alerts you by email or webhook when the score drops past a threshold you set.

Frequently Asked Questions

What is a good SEO score for a new website?

A good SEO score for a new website is 70 or above, the same as for any other site; the score does not know how old the domain is. New sites tend to lose points on a missing sitemap, no structured data, and thin pages. Fix the title, meta description, H1, canonical, and Open Graph tags first.

Is an SEO score of 100 possible?

Yes, 100 is possible, and it is rare: only about 8% of the audits we run reach even 80. A 100 means passing every check, including ones that depend on server response time. It is not a sensible goal. The last few points come from details that do not change how a page ranks.

What is an SEO grade?

An SEO grade is the letter version of an SEO score: A+ for 90–100, A for 80–89, B for 70–79, C for 60–69, D for 50–59, and F below 50. Different tools draw the bands differently, so a B from one tool is not the same as a B from another. Compare grades only within the same tool.

Does a higher SEO score guarantee better Google rankings?

No. An SEO score measures technical and on-page factors. It does not measure backlinks, domain authority, or content quality, and Google does not use it. Fixing the issues behind a low score removes obstacles to indexing and ranking; it does not create the reasons to rank.

What is the difference between an SEO score and a PageSpeed score?

An SEO score is a composite measure across meta, technical, performance, social, and accessibility checks. A PageSpeed score (Google Lighthouse) measures only performance and Core Web Vitals. Our SEO score includes performance as one of five categories, giving you a broader picture.

How accurate are automated SEO scores?

Automated SEO scores are reliable at what they check: whether a tag exists, how long it is, whether the page is served over HTTPS, how large the HTML is. They cannot judge whether the content answers the query or whether the title is persuasive. Treat the score as a defect count for the page's setup, not a verdict on the page.

Can I check my competitor's SEO score?

Yes. The SEO Score API audits any publicly accessible URL, including competitor pages, so you can compare your score with theirs and see which checks they pass that you do not.

Free SEO Score Checker: Audit Any Website

Aaron VanSledright — Mon, 12 Oct 2026 14:00:05 +0000

SEO Score API is a REST API that scores any URL on 50+ SEO and AI readability checks and returns a score from 0 to 100 with a letter grade — for free. The free tier gives you 2 audits per day with a score for every category: meta tags, technical SEO, performance, social signals, and accessibility. The free response details 2 checks per category and the top 2 fixes; paid plans return every check and fix. No credit card required.

A free SEO score checker is a tool that analyzes your website and returns an objective measurement of its search optimization health. Unlike manual audits that take hours, an API-based checker usually returns results in seconds.

What Does the Free SEO Checker Include?

The free tier scores your page on the same 50+ core checks across five categories that paid plans use. The free response shows every score, 2 checks per category in detail and the top 2 fixes; paid plans return every check and fix. The free limit is 2 audits per day.

The five scoring categories are:

Meta — title tag, meta description, canonical, robots, viewport
Technical — H1, structured data (JSON-LD), sitemap detection, hreflang, HTTPS
Performance — server response time, compression, resource loading, redirect count
Social — Open Graph title/description/image, Twitter Card tags
Accessibility — image alt text, ARIA landmarks, language attribute, form labels

Each category returns a sub-score (0–100) and letter grade so you can see exactly where your site excels and where it falls short.

How Do You Get a Free SEO Score?

You get a free SEO score by signing up for an API key, then making a single GET request to the audit endpoint. The entire process takes under two minutes.

Step 1 — Sign up for a free key:

curl -X POST https://seoscoreapi.com/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Step 2 — Run your first audit:

curl "https://seoscoreapi.com/audit?url=https://yoursite.com" \
  -H "X-API-Key: YOUR_KEY_HERE"

Step 3 — Read your results:

{
  "url": "https://yoursite.com",
  "score": 76,
  "grade": "B",
  "priorities": [
    { "issue": "Missing og:image tag", "severity": "medium" }
  ]
}

The priorities array lists every individual check failure with a plain-English description of what to fix.

What Does the Audit Actually Check?

The audit covers 50+ individual checks on the free tier and 80+ on paid plans. Here are some of the most impactful ones:

Meta checks:

Title tag present and within 50–60 characters
Meta description present and within 150–160 characters
Canonical URL set correctly
Viewport meta tag present (mobile optimization)

Technical checks:

Single H1 tag present
JSON-LD structured data detected
HTTPS enforced
XML sitemap detectable

Performance checks:

Server response time under 600ms
GZIP or Brotli compression enabled
No 4xx or 5xx response codes

Social checks:

og:title, og:description, og:image all present
Twitter Card meta tags present

Accessibility checks:

All images have alt attributes
Page has a lang attribute on <html>
Heading hierarchy is logical (H1 → H2 → H3)

Free vs. Paid: What Is the Difference?

Feature	Free	Starter ($5/mo)	Basic ($15/mo)	Pro ($39/mo)
Audits	2/day	200/mo	1,000/mo	5,000/mo
Requests per minute	2	10	30	60
Scored on the 50+ core checks	Yes	Yes	Yes	Yes
Every check and fix in the response	2 per category, top 2 fixes	Yes	Yes	Yes
SXO, AEO & AIO scores	No	Yes	Yes	Yes
Batch audits	No	Yes	Yes	Yes
URL monitoring	No	5 URLs	10 URLs	25 URLs

For one-off checks, competitor research, or testing integrations, the free tier is all you need. For agencies running audits across client portfolios, paid plans provide the volume and extended scoring.

How Can I Use the Free Checker in My Projects?

You can use the free SEO checker in any project that can make HTTP requests. Common use cases include:

Pre-launch checks — audit your site before going live to catch missing meta tags
Competitor research — score competitor URLs to identify gaps
CMS testing — verify that theme or plugin changes didn't break SEO elements
Portfolio reviews — quickly assess the SEO health of sites you're pitching on
CI/CD gates — fail deployments if the score drops below a threshold

The Python SDK makes integration especially fast:

from seoscoreapi import signup, verify, audit

signup("you@example.com")  # emails a 6-digit code
key = verify("you@example.com", input("Code from the email: "))
result = audit("https://yoursite.com", api_key=key)
print(f"Score: {result['score']} ({result['grade']})")

Is the Free SEO Checker Accurate?

Yes. The free tier uses the same analysis engine as all paid plans — headless Chromium via Playwright, which renders JavaScript before scoring. This means the audit sees your page the way Google's crawler does, not just the raw HTML source.

The score reflects technical and on-page factors. It does not measure backlinks, domain authority, or content quality — those require separate tools.

Frequently Asked Questions

Is the free SEO checker really free?

Yes, the free tier is genuinely free with no credit card required. You get 2 audits per day, each scored on 50+ checks and returned as JSON. Compared to paid plans, the free response details 2 checks per category and the top 2 fixes, and it leaves out SXO/AEO/AIO extended scoring, history, and batch auditing; audit volume is lower too.

Do I need to install anything to use the free checker?

No installation is required. The SEO Score API is a REST API — you make HTTP requests from any language, terminal, or tool. There is also a Python SDK (pip install seoscoreapi) and a Node.js SDK (npm install seoscoreapi) if you prefer a client library.

How long does a free SEO audit take?

A free SEO audit usually returns in seconds. Pages with heavy JavaScript or slow server responses take longer. The API uses headless Chromium to render the page before scoring, which accounts for most of the processing time.

Can I check any website's SEO score for free?

Yes. You can audit any publicly accessible URL — your own site, competitor sites, or client sites. URLs behind login walls or on private networks cannot be audited.

What is the difference between free and paid plans?

The free plan limits you to 2 audits per day and 2 requests per minute. Paid plans start at $5/month for 200 audits and add SXO/AEO/AIO extended scores, batch auditing (multiple URLs in one request), and URL monitoring with score-drop alerts.

How do I upgrade from the free plan?

Log in to your developer portal at seoscoreapi.com/portal with your registered email. From there you can upgrade to any paid plan via Stripe. Your API key stays the same — limits are updated immediately on upgrade.

Fail the build when SEO breaks: SEO checks in CI with GitHub Actions

Aaron VanSledright — Thu, 08 Oct 2026 12:58:53 +0000

Short answer: to run SEO checks in CI, add the SeoScoreAPI/seo-audit-action step to a GitHub Actions workflow with a URL, an API key and a threshold. It calls the SEO Score API GET /audit endpoint, writes the score to the job summary, and exits non-zero when the score is under the threshold (default 80). A free key covers 2 audits a day, so on the free tier run it on pushes to main, not on every pull request.

I'm Aaron, the solo developer behind SEO Score API and this action. This post is the workflow I'd actually commit, plus the parts that tend to surprise people.

How do I run an SEO audit in GitHub Actions?

Get a key (free, email plus a 6-digit code, no card), add it as a repository secret named SEO_SCORE_API_KEY, and commit this as .github/workflows/seo.yml:

name: SEO check

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  seo:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: SEO audit
        id: seo
        uses: SeoScoreAPI/seo-audit-action@v1
        with:
          url: "https://your-site.com"
          api-key: ${{ secrets.SEO_SCORE_API_KEY }}
          threshold: 80

      - name: Print result
        if: always()
        run: echo "Score ${{ steps.seo.outputs.score }} (${{ steps.seo.outputs.grade }}), report ${{ steps.seo.outputs.report-url }}"

That is the whole thing. No checkout step is needed, because the action audits a URL, not your repository.

What does the SEO audit action do?

It is a composite action: a shell step that runs curl and jq. You can read all of it in action.yml. The inputs and outputs for the standard audit:

Input	Default	Meaning
`url`	required	The page to audit
`api-key`	required	Your SEO Score API key
`threshold`	`80`	Minimum score to pass, 0-100
`fail-on-threshold`	`true`	Set to `false` to report without failing

Outputs are score, grade, issues (the number of fixes returned) and report-url. The score is a decimal such as 65.567, and the action compares it numerically. There are also deep-audit-* inputs for the slower Deep Site Audit (Pro and Ultra plans), which I'm leaving out here.

The audit itself is the same GET /audit call you can make by hand: 55 checks per URL on the free tier, 83 on paid plans, across meta and content, technical SEO, social tags, performance, accessibility and AI readability.

How do I fail the build on specific checks, not just the score?

A score threshold catches gradual decay. It is weak at catching one fatal change, because a single check is averaged in with dozens of others.

For that, skip the action, call the API once, and gate on both the score and a list of named checks. This is a complete workflow:

name: SEO gate

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  seo-gate:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    env:
      SITE_URL: "https://your-site.com"
      MIN_SCORE: "80"
      NO_FAIL: '["status_code","https","title","meta_description","h1"]'
      NO_WARN: '["canonical","robots_meta"]'
    steps:
      - name: Run audit
        env:
          SEOSCORE_API_KEY: ${{ secrets.SEO_SCORE_API_KEY }}
        run: |
          curl -sS --fail-with-body --max-time 120 -G \
            -H "X-API-Key: $SEOSCORE_API_KEY" \
            --data-urlencode "url=$SITE_URL" \
            -o audit.json "https://seoscoreapi.com/audit" \
            || { cat audit.json; exit 1; }

      - name: Enforce score and required checks
        run: |
          SCORE=$(jq -r '.score' audit.json)
          BROKEN=$(jq -r --argjson nofail "$NO_FAIL" --argjson nowarn "$NO_WARN" '
            .audit[].checks[]
            | select(
                (.status == "fail" and (.name | IN($nofail[], $nowarn[])))
                or (.status == "warning" and (.name | IN($nowarn[])))
              )
            | "- \(.name) (\(.status)): \(.recommendation // "no detail")"' audit.json)

          echo "SEO score: $SCORE (minimum $MIN_SCORE)"
          if awk -v s="$SCORE" -v t="$MIN_SCORE" 'BEGIN { exit (s + 0 < t + 0) ? 0 : 1 }'; then
            echo "::error::SEO score $SCORE is below $MIN_SCORE"
            exit 1
          fi
          if [ -n "$BROKEN" ]; then
            echo "::error::Required SEO checks failed"
            echo "$BROKEN"
            exit 1
          fi

The names are real check names from the response (.audit.<category>.checks[].name). Run against a saved audit of https://example.com with MIN_SCORE at 60, the gate step exits 1 and prints:

SEO score: 65.567 (minimum 60)
::error::Required SEO checks failed
- meta_description (fail): Add a meta description (150-160 chars)
- h1 (fail): Add exactly one H1 tag
- canonical (warning): Add a canonical tag to prevent duplicate content issues

Two things to know. First, a check's status is pass, warning, fail or info, and some serious problems are only a warning. A missing canonical tag is one, and so is a noindex robots meta tag. That is why there are two lists: checks in NO_WARN break the build on a warning too. Second, this version needs a paid key to be useful. Free keys get the full score but a shortened checks array per category, so a check you listed may not be in the response at all. The score threshold works on any plan.

How many audits will CI use?

One audit per URL per run. That makes the free tier's limits easy to reason about:

Plan	Price	Audits	Requests per minute	Rough CI fit
Free	$0	2 per day	2	One URL, on pushes to `main`
Starter	$5/month	200 per month	10	One URL on every pull request for a small team
Basic	$15/month	1,000 per month	30	A handful of URLs per pull request
Pro	$39/month	5,000 per month	60	Many URLs, busy repository

Ultra is $99/month for 25,000 audits.

What goes wrong in practice?

It audits what is deployed. The API fetches a public URL. It cannot see localhost on your runner. On a push to main that means the gate runs after the deploy, so make the SEO job depend on your deploy job (needs: deploy) or it will audit the previous version. To block a merge before production, point url at a preview deployment.
Running out of quota fails the build. The action uses curl -f, so a 429 (daily limit reached, or more than your requests per minute) ends the step with "Failed to reach SEO Score API". On the free tier the third run of the day will be red for that reason, not because your SEO changed.
Audited domains appear on a public scoreboard unless you opt the key out: curl -X PUT "https://seoscoreapi.com/scoreboard/opt-out?opt_out=true" -H "X-API-Key: YOUR_API_KEY". Do this before auditing preview URLs.
Pick a threshold below your current score. Run it once with fail-on-threshold: false, then set the threshold a few points under what you got. A gate that is red on day one gets deleted.
Give it time. Most audits return in seconds, but while writing this I saw one take about a minute. Hence --max-time 120 and a 5 minute job timeout.

When is Lighthouse CI or another tool a better choice?

Tool	Runs where	Better choice when
SEO Score API action	Hosted API, audits a public URL	You want one score and a fix list covering on-page, technical and AI-readability checks, with no browser to install
Lighthouse CI	Your CI runner, against a local build or a URL	You want to gate before anything is deployed, you care most about performance budgets, or you want no third party and no quota
PageSpeed Insights API	Google's servers, public URL	You want Core Web Vitals, including real-user data where Google has it
Open-source link checkers and crawlers (lychee, Scrapy)	Your CI runner	You need every page crawled for broken links or custom rules

Lighthouse CI is free and open source, and its SEO category covers the basics (title, meta description, crawlability, valid robots.txt). If that is all you need, use it and skip the API key. Plenty of teams run both.

FAQ

Is there an SEO audit GitHub Action?
Yes: SeoScoreAPI/seo-audit-action@v1. It takes url, api-key and threshold, and fails the job when the score is below the threshold.

Can I run SEO checks in CI for free?
Yes, within 2 audits per day and 2 requests per minute. For a pull-request gate you will want the $5 Starter plan (200 audits a month) or Lighthouse CI, which has no quota.

Does it work with GitLab CI, CircleCI or Jenkins?
Yes. The action is a wrapper around one curl call, and the second workflow above is plain shell that runs anywhere curl and jq are installed.

Can it audit a pull request before it is deployed?
Only if the pull request has a public preview URL. For a build that never leaves the runner, use Lighthouse CI.

Will this improve my rankings?
No tool can promise that. It stops you from shipping regressions such as a missing title or an accidental noindex, which is a narrower claim.

A free SEO audit API for developers: score any URL with one request

Aaron VanSledright — Thu, 08 Oct 2026 12:58:52 +0000

Short answer: yes, there is a free SEO API you can call from code. SEO Score API has a free tier of 2 audits per day with no credit card: send GET /audit?url=... with an X-API-Key header and you get back JSON with a 0-100 score, a letter grade, per-category scores and a list of fixes. The free tier runs 55 checks per URL; paid plans run 83 and start at $5 a month.

I'm Aaron, the solo developer who built it, so read this as a tutorial from the person with the bias. I've tried to be plain about what the free tier leaves out and when you should use something else.

How do I check a website's SEO score programmatically?

Three steps: get a key, make one GET request, read the JSON.

Sign up on the homepage or do it from the terminal. Signup is two calls because the key is tied to a verified email address:

curl -s -X POST https://seoscoreapi.com/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# a 6-digit code arrives by email
curl -s -X POST https://seoscoreapi.com/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'

Then audit a URL:

curl -s --max-time 120 -H "X-API-Key: YOUR_API_KEY" \
  "https://seoscoreapi.com/audit?url=https://example.com" \
  | jq '{score, grade, issues: (.priorities | length)}'

With a paid key, that printed this when I ran it for this post:

{
  "score": 65.567,
  "grade": "C",
  "issues": 8
}

Note that score is a decimal, not an integer. Compare it as a number.

What does the SEO audit API return?

Here is an excerpt of the real response for https://example.com, trimmed to one check per category and one fix. I removed items; I did not rename or add any field.

{
  "url": "https://example.com",
  "score": 65.567,
  "grade": "C",
  "response_code": 200,
  "response_time": "0.50s",
  "audit": {
    "meta": {
      "score": 52.75,
      "checks": [
        {
          "name": "title",
          "status": "warning",
          "value": "Example Domain",
          "score": 50,
          "recommendation": "Title is short (14 chars). Aim for 50-60 characters."
        }
      ]
    },
    "technical": {
      "score": 70.0,
      "checks": [
        { "name": "response_time", "status": "pass", "value": "0.50s", "score": 100 }
      ]
    }
  },
  "priorities": [
    {
      "severity": "high",
      "category": "meta",
      "issue": "Missing meta description",
      "fix": "Add a meta description (150-160 chars)",
      "plain_english": "The page has no summary for search results, so Google picks a random snippet that may not make people click.",
      "who_fixes_it": "content"
    }
  ],
  "ai_readability": {
    "ai_readability_score": 43,
    "ai_readability_grade": "F"
  }
}

The audit object has five categories: meta, technical, social, performance and accessibility. Each has a score and a checks array, and each check has a name, a status (pass, warning, fail or info), the value found and usually a recommendation. priorities is the fix list sorted by severity, and who_fixes_it is developer, content or marketing. The response also carries a core_web_vitals block, which can come back with "status": "unavailable" when the upstream lookup fails, so don't assume it is populated.

How do I call it from Python?

There is an official client on PyPI (pip install seoscoreapi). It is a thin wrapper over requests:

import os
import sys

from seoscoreapi import audit

url = sys.argv[1] if len(sys.argv) > 1 else "https://example.com"
result = audit(url, api_key=os.environ["SEOSCORE_API_KEY"])

print(f"{result['url']}: {result['score']}/100 ({result['grade']})")

for name, category in result["audit"].items():
    print(f"  {name:<14} {category['score']}")

for p in result["priorities"]:
    print(f"  [{p['severity']}] {p['issue']} ({p['who_fixes_it']})")

Output from my run:

https://example.com: 65.567/100 (C)
  meta           52.75
  technical      70.0
  social         50.0
  performance    96.25
  accessibility  66.667
  [high] Missing meta description (content)
  [high] No H1 tag found (content)
  [medium] Thin content (133 words) (content)
  ...

audit() raises requests.HTTPError on a non-2xx response, so a 401 (bad key) or 429 (out of quota, or too many requests per minute) surfaces as an exception.

How do I call it from Node.js?

Same idea with the npm package (npm install seoscoreapi). It uses the built-in fetch, so you need Node 18 or later:

const { audit } = require("seoscoreapi");

async function main() {
  const url = process.argv[2] || "https://example.com";
  try {
    const result = await audit(url, process.env.SEOSCORE_API_KEY);
    console.log(`${result.url}: ${result.score}/100 (${result.grade})`);
    for (const p of result.priorities) {
      console.log(`  [${p.severity}] ${p.issue} -> ${p.fix}`);
    }
  } catch (err) {
    // err.status is the HTTP status: 401 bad key, 429 out of quota or too fast
    console.error(`Audit failed (${err.status || "network"}): ${err.message}`);
    process.exit(1);
  }
}

main();

If you'd rather not add a dependency, the curl call above translates directly to fetch or requests.get. There is nothing else to the protocol.

What does the free tier not include?

The free tier is real (no trial clock, no card), but it is small, and the response is trimmed. From the pricing table and the API docs:

2 audits per day and 2 requests per minute. Enough to test the API or watch one page. Not enough to audit a sitemap.
55 checks, not 83. The SXO, AEO and AIO scoring blocks are paid. A free response has an _extended_gated placeholder where they would be.
A capped fix list and capped check detail. The overall score, grade and category scores are complete, but the priorities list and the per-category checks arrays are shortened on free keys. A _priorities_gated or _gated field tells you how many more there are.
No history, batch or monitoring. Score deltas, POST /audit/batch and scheduled monitoring start on the $5 Starter plan.
No accessibility (WCAG) audit, GEO audit or AI citation tracking. Those are paid endpoints.
One URL per call. /audit scores a page. It does not crawl a site.

Two more things worth knowing before you build on it. Audits add the audited domain to a public scoreboard unless you opt your key out with PUT /scoreboard/opt-out?opt_out=true. And set a client timeout of a minute or two: the site says most pages finish in about two seconds, but in my runs for this post one call took under 7 seconds and another took about a minute.

Paid plans, for reference: Starter $5/month (200 audits), Basic $15 (1,000), Pro $39 (5,000), Ultra $99 (25,000).

Which free SEO API should I use?

It depends on what you are measuring. I'd pick a different tool in several of these cases.

Tool	Cost	What you get	Better choice when
SEO Score API (free tier)	$0, 2 audits/day	One score plus on-page, technical, social and AI-readability checks as JSON	You want a single number and a fix list from one HTTP call, with nothing to host
Google PageSpeed Insights API	Free	Lighthouse lab data plus real-user Core Web Vitals where Google has them	Performance is the question. It is Google's own data and I can't match it
Lighthouse CI	Free, open source	Lighthouse runs on your own machine or CI runner	You need to test a local build or a page behind a login, or you want no third party and no quota
Open-source crawlers (Scrapy, advertools)	Free, you host it	Whatever you program it to collect, across a whole site	You need site-wide crawling, broken-link checks or custom rules, and can maintain it

None of these, mine included, do keyword research or rank tracking. That is what Ahrefs, Semrush and Moz are for.

FAQ

Is there a free SEO API for developers?
Yes. SEO Score API's free tier gives 2 audits per day and 2 requests per minute, with no credit card. Google's PageSpeed Insights API is also free and is the better choice for performance data.

How many checks does the free tier run?
55 per URL, across meta and content, technical SEO, social tags, performance, accessibility and AI readability. Paid plans add 28 SXO, AEO and AIO checks for 83.

Do I need a credit card?
No. Signup is an email address and a 6-digit verification code.

Can I audit a whole site?
Not with one free call. /audit takes one URL. Batch audits (up to 10 URLs per request) and multi-page crawls are on paid plans.

Can I use it in CI?
Yes. There is an official GitHub Action, SeoScoreAPI/seo-audit-action, that fails a build when the score drops below a threshold. On the free tier, budget for 2 runs a day.

Where are the full docs?
The OpenAPI reference is at seoscoreapi.com/docs.

One Deep Audit for $12: Full Report, No Subscription

Aaron VanSledright — Mon, 05 Oct 2026 17:47:19 +0000

You can now buy a single Deep Audit for $12. There is no plan to sign up for and nothing to cancel. Open a report, look at the free version, and pay only if you want the rest.

What you see for free

Every hosted report at seoscoreapi.com/report/yourdomain.com opens as a free look. It shows the overall score and grade, how many issues were found at each severity, and the title of the most important one. The remaining issues and their fixes are hidden until the report is unlocked.

That is enough to answer the first question most people have, which is whether the site has a problem worth paying to understand.

What $12 unlocks

The single purchase does two things:

It unlocks the full hosted report for that domain. Every issue, every fix, and a plain-English sentence for each one that says what is wrong and who should fix it.
It gives you one Deep Audit credit. A Deep Audit is the long-form audit: thousands of checks from a public catalog of more than 14,000, scored across nine sections, with an AI analysis pass on top. It takes about 90 seconds and runs in the background.

You also get the exports. The unlocked report downloads as a PDF, as Markdown, or as a CSV, so the fix list can go straight into a ticket tracker or a client email.

A free API key is created for the email address you pay with. You don't need to use it, but it is there if you later want to run audits from code.

Who this is for

A site owner who wants one answer. You don't run audits every week. You want to know what is wrong with one site, once.
An agency checking a prospect. Run the audit before a pitch, export the PDF, and bring real findings to the first call.
A developer about to take on a rebuild. Get a baseline before you touch anything, so the improvement is measurable afterwards.

When a pack or a plan costs less

The single is the right buy for one report. If you need more, the price per audit drops:

Option	Deep Audits	Price	Per audit
Single	1	$12	$12.00
3-pack	3	$29	$9.67
10-pack	10	$79	$7.90
Pro plan	20 a month	$39/mo	$1.95
Ultra plan	100 a month	$99/mo	$0.99

Pack credits are valid for 12 months. Pro and Ultra also include the standard audit API (5,000 and 25,000 audits a month), so anyone auditing regularly is better off on a plan. Details are in Buy Deep Audit Credits and on the pricing section.

How to buy one

Open https://seoscoreapi.com/report/yourdomain.com.
Enter your email in the unlock box and pay by card.
You land back on the full report. A button on the receipt starts the Deep Audit.

If you want to know what a Deep Audit scores before you buy, Reading a Deep Audit Report walks through each section, and the check catalog lists every check by name.

Frequently asked questions

Is the $12 a subscription?

No. It is a one-time charge. Nothing renews.

Does the unlock cover more than one site?

No. One purchase unlocks the full report for one domain and includes one Deep Audit credit.

Do I need an account?

No. You pay with an email address. A free API key is created for that address so the unlock follows you if you sign in later.

Replacing Screaming Frog with an API: A 10,000-URL Agency Workflow

Aaron VanSledright — Mon, 05 Oct 2026 14:00:07 +0000

Screaming Frog SEO Spider is the most-installed SEO tool in agency workflows. Most audits we've seen referenced over the past decade started with a Screaming Frog crawl. It's a good piece of software. It is also a desktop application that has to be running on someone's laptop, that has to be configured per-project, that has to be re-run when anything changes, and that produces a CSV which then has to be opened in Excel and triaged by hand.

This post is for agencies and in-house teams asking the obvious question: what does the API equivalent look like, and is it actually cheaper? The short answer is yes, with a different shape of workflow. The longer answer is below.

What Screaming Frog is good at

Crediting where credit is due. Screaming Frog does several things well:

Crawl discovery. Point it at a URL and it walks every internal link. You don't need to know your sitemap, your sitemap doesn't have to be correct, you'll find pages the sitemap forgot.
Per-page detail. It pulls headings, meta tags, internal/external links, response codes, redirect chains, and a long tail of properties.
One-off depth. Configure once, crawl once, walk away.

If you're doing a single deep audit of a single site and never re-running it, Screaming Frog is fine. Pay the £199/year and move on.

What it isn't good at

Where it breaks down for an agency or in-house team running ongoing audits:

It's a desktop app. Someone's laptop has to be on, awake, and not crashing. For a 50,000-URL site that's a 6-hour crawl on a tuned machine.
Crawls don't compose. Last week's crawl is a CSV on someone's hard drive. There is no built-in "what changed since last week" view that isn't manual diffing.
No native scoring or grading. It tells you a <title> is 67 characters long. It does not tell you "this page scores 84 and your competitor scores 91 and here's why."
No API surface. You cannot trigger it from a CI pipeline, schedule it from a server, or hand a button to a non-technical colleague.
Per-seat licensing. Each analyst needs their own license, their own configuration, their own copy of the CSV.

For a team of three doing weekly audits across twelve clients, those constraints stop being theoretical and start eating real hours.

The API-equivalent workflow

Same outcome — a scored audit of every URL on the site — restructured as a server-side job:

import requests, csv, os
import xml.etree.ElementTree as ET

API_KEY = os.environ["SEOSCORE_API_KEY"]
BASE = "https://api.seoscoreapi.com"

def crawl(site):
    """Pull URLs from the sitemap, recursing into indexes."""
    ns = {"sm": "http://www.sitemaps.org/schemas/sitemap/0.9"}
    def _collect(url):
        root = ET.fromstring(requests.get(url, timeout=20).text)
        if root.tag.endswith("sitemapindex"):
            urls = []
            for child in root.findall(".//sm:sitemap/sm:loc", ns):
                urls.extend(_collect(child.text))
            return urls
        return [l.text for l in root.findall(".//sm:url/sm:loc", ns)]
    return _collect(f"{site}/sitemap.xml")

def audit_all(urls):
    rows = []
    for i in range(0, len(urls), 50):
        r = requests.post(
            f"{BASE}/audit/batch",
            headers={"X-API-Key": API_KEY},
            json={"urls": urls[i:i+50]},
            timeout=300,
        )
        r.raise_for_status()
        rows.extend(r.json()["results"])
    return rows

urls = crawl("https://client.com")
print(f"Discovered {len(urls)} URLs")
results = audit_all(urls)
print(f"Audited {len(results)} pages")

Sixty lines, end to end. Run it on a server. Output a CSV. Hand the CSV to the analyst, or pipe it into a dashboard, or post it to Slack.

The crawl-discovery gap (and how to close it)

The honest tradeoff: a sitemap-based crawl is not a true crawl. If a page exists but isn't in the sitemap, you won't find it. Screaming Frog walks every link and finds those orphans.

For most sites this matters less than you'd think. Marketing sites publish complete sitemaps. Shopify, WooCommerce, WordPress with Yoast — all generate exhaustive sitemaps automatically. If you've audited the sitemap, you've audited the site that Google can see.

For sites where it does matter (legacy CMS, fragments of static HTML hand-rolled into Apache, archives that nobody linked into the nav), a one-time Screaming Frog crawl to generate the URL list, plus the API for ongoing scoring, is a perfectly reasonable hybrid. The API doesn't have to replace every part of the workflow to be a 10x improvement on the parts it does replace.

What the API does that the desktop can't

The interesting tradeoff isn't "what we lost" — it's "what we gained that wasn't possible before."

Historical comparison. Every audit's score is stored against your key. Run the same audit weekly and you have a per-URL trend line, with deltas surfaced automatically. The historical tracking post has the full API. There is no equivalent in Screaming Frog without manually saving and diffing CSVs.

Composability. The audit results are JSON. Pipe them into anything. We've seen teams build:

Slack alerts that fire when any tracked client drops 3+ points.
HTML dashboards generated from /history/domains for monthly client reviews.
Re-audits triggered automatically when a new deploy lands in production.

Side-by-side comparisons. /compare audits two URLs in parallel and returns a diff. Use it for client-vs-competitor pitches, before/after migration checks, or A/B preview/production validation. The Stripe/Square/Adyen comparison post shows the format.

AI readability and GEO scoring. SEO Score API runs the kind of on-page SEO checks Screaming Frog covers plus an additional layer specifically for how LLMs read your content. That's not in Screaming Frog at all and isn't going to be — it's a different category of analysis. The GEO optimization guide and AI readability post cover what's in there.

Shareable reports and badges. Every audited URL gets a publicly shareable report at /report/{domain} and an SVG score badge. Drop the badge in client decks; drop the report URL in emails. There's no Screaming Frog equivalent — its outputs are CSVs that only the analyst sees.

Cost comparison, honestly

Screaming Frog SEO Spider: £199/year per seat (~$250/year).

SEO Score API:

Tier	Audits/mo	Annual cost	Use case
Basic	1,000	$180/year	Solo SEO, 3-5 small clients
Pro	5,000	$468/year	Agency with 10-20 clients, weekly audits
Ultra	25,000	$1,188/year	Agency with 30+ clients or one large enterprise site

A two-person agency replacing two Screaming Frog seats (~$500/year) gets the same audit coverage on Pro for less money, plus everything in the "what the API does that the desktop can't" section. A larger agency replacing 4-5 seats (~$1,200/year) lands on Ultra and gets unlimited history retention, which on its own is worth the difference.

The break-even is rough but real: somewhere around 3 seats of Screaming Frog, Ultra is cheaper and strictly more capable.

What we keep Screaming Frog around for

We don't pretend the API replaces 100% of use cases. Where Screaming Frog still wins:

Crawling sites with broken or missing sitemaps.
Following redirect chains across external links to figure out what an old domain ended up redirecting to.
One-shot deep audits where you want every property of every page in a single CSV and you'll never re-run the audit.
Legacy site migrations where you need to map old URLs → new URLs by content hash.

Use the right tool for the job. The point isn't to eliminate Screaming Frog — it's to stop using it for the weekly and per-deploy and cross-client work that it was never designed to do, where its constraints turn into real cost.

The migration path

If you're an agency moving from Screaming Frog-only to API-first, the order we'd suggest:

Pick your three highest-effort clients. Audit their sites with the API. Compare the output to your most recent Screaming Frog audit. Confirm the coverage is equivalent for your purposes.
Stand up a weekly job. Cron + a Python script + Slack webhook. The agency monitor setup post has the full walkthrough.
Move quarterly client reports onto the API output. The HTML report at /report/{domain} is shareable; the badge is droppable; the history endpoint generates trend charts.
Use Screaming Frog only for the deep one-off audits where its discovery wins. That's roughly twice a year per client, not weekly.

Most agencies that do this end up shifting 80–90% of their crawler-hours to the API and keeping Screaming Frog around for the long-tail cases. Total cost drops, total throughput goes up, and the analyst time freed up goes into actual fixes instead of running spider crawls overnight.

Getting started

If you're a solo or small agency, Basic ($15/mo) covers 3-5 sites at weekly cadence. If you're running an agency at scale and Screaming Frog has become a bottleneck, Pro ($39/mo) is the sweet spot. For the largest agencies with 30+ clients, Ultra ($99/mo) replaces the seat-licensing math entirely.

One SEO Tools API, Five Workflows Your Team Probably Already Needs

Aaron VanSledright — Mon, 28 Sep 2026 14:00:03 +0000

The phrase "SEO tools API" gets searched a lot, and it usually means something different to whoever's typing it. Some people mean "an API that audits one page." Some mean "an API that pulls multiple SEO tools together." Some mean "an API I can wire into my existing tools."

SEO Score API is the first of those, but it functions as the second and third — because once you have a structured audit response, it slots into existing tooling without much glue. This post walks through the five workflows engineering and agency teams build on top of the same endpoint, all from one API key.

Workflow 1: CI gates

The most common first integration. You hit /audit?url=... against your preview deploy in GitHub Actions and fail the build if the score regresses.

- run: |
    SCORE=$(curl -s -H "X-API-Key: $KEY" \
      "https://seoscoreapi.com/audit?url=$PREVIEW" | jq .score)
    [ "$SCORE" -lt 85 ] && exit 1

That's the whole gate. Detailed walkthrough in Wiring an SEO analyzer API into a Next.js build and the published GitHub Action.

Workflow 2: Scheduled monitoring

Same endpoint, different schedule. Instead of one audit per PR, run a list of URLs nightly or weekly and alert on regressions.

# nightly_monitor.py
from seoscoreapi import audit
import os, requests

URLS = ["https://site.com/", "https://site.com/pricing", ...]
for url in URLS:
    r = audit(url, api_key=os.environ["KEY"])
    if r["score"] < 80:
        requests.post(os.environ["SLACK_HOOK"], json={
            "text": f"⚠️ {url} scored {r['score']} ({r['grade']})"
        })

Cron it, point it at Slack, ship it. SEO Monitor API: score tracking with webhooks and Slack alerts has the production-grade version with deduplication and SLA windows.

Workflow 3: AI agents

LLMs are bad at reading screenshots and good at reading JSON. The same /audit response that powers a CI gate is what you hand an agent when you want it to fix SEO issues autonomously.

findings = audit(url, api_key=KEY)
agent_prompt = f"""
You're an SEO engineer. Here's the audit JSON for {url}.
Fix the top 3 failing checks. Return a unified diff.

{json.dumps(findings, indent=2)}
"""
diff = claude.messages.create(model="claude-opus-4-7", ...)

That's it. The structured response is the contract; the agent just acts on it. Build an AI SEO Agent walks through the full loop with Claude, and we ship an MCP server so Claude and Cursor can call the API natively.

Workflow 4: Client and stakeholder reports

The audit response is structured to be rendered as well as acted on. Three rendering options, in order of effort:

Lowest-effort: link clients to /report/{domain} — that's our hosted report URL, auto-refreshed when the audit re-runs. Zero code, branded enough for most.

Medium-effort: wrap the /audit JSON in a Jinja template, send as HTML email via your SMTP of choice. ~80 lines. Full walkthrough in Generating weekly client SEO reports automatically.

Highest-effort: build your own white-label dashboard on top of the API. The white-label SEO reports post covers this.

Same endpoint, three different report surfaces.

Workflow 5: Status badges

Useful for open-source projects, public marketing pages, and internal dashboards. Embed an SVG that reflects the current score:

![SEO Score](https://seoscoreapi.com/badge/your-domain.com)

The badge re-renders from the most recent audit. Run a weekly cron that audits your domain and the badge stays current. Free tier covers this for one domain forever.

Why one endpoint instead of five

Some SEO APIs split their product across endpoints — one for "audit," one for "monitor," one for "report." That's a UX choice with a real cost: every new endpoint is a new response shape your code has to learn, a new error model to handle, a new SDK method to remember.

We deliberately built around one endpoint (/audit) returning one response shape. The five workflows above all consume the same JSON. That means:

The Jinja template you write for the weekly client report works on a CI gate's output too.
The Slack alert format you wrote for nightly monitoring works on PR-blocking failures.
The agent prompt you tuned against last Tuesday's audit still works against tomorrow's.

The endpoint is the API. Everything else is glue you write once and reuse.

What ties the workflows together

One API key. One endpoint. One response shape.

If you're evaluating SEO tools APIs and the comparison matrix gets complicated — "this one has 6 endpoints, this one has 12, this one has webhooks but not batches" — that's a signal that the surface is too wide. The narrower the API, the more workflows it actually fits.

Sign up for free and see if a single /audit response slots into more places than you'd expect. The free tier (2/day, no card) is enough to prototype any of the five workflows above.

The SEO Checker API: Pass/Fail SEO Checks for Code, Not Dashboards

Aaron VanSledright — Mon, 21 Sep 2026 14:00:05 +0000

An SEO checker API is an SEO checker that returns its results as machine-readable JSON instead of a dashboard. Every check returns a structured pass/fail, a numeric score, and the value found — so the next thing in your pipeline can act on it without a human in the loop.

That distinction is the entire reason to use an API over a tool like Screaming Frog or a SaaS dashboard. The dashboard is for humans clicking through findings. The API is for code that already knows what to do once it has the answer.

What "pass/fail per check" actually means

When you hit GET /audit?url=https://example.com against SEO Score API, you get back a response that looks like this (trimmed):

{
  "score": 78,
  "grade": "B",
  "audit": {
    "meta_content": {
      "score": 92,
      "checks": [
        {"id": "title_present", "status": "pass", "value": "Example Domain"},
        {"id": "title_length", "status": "pass", "value": 14, "ideal": "30-60"},
        {"id": "meta_description_present", "status": "fail", "value": null}
      ]
    },
    "technical_seo": { "...": "..." }
  }
}

status is one of pass, warn, fail. That single field is the whole product surface for code-driven workflows: filter the array, count the failures, threshold on category sub-scores, write a diff against last week's run. None of that requires reading the dashboard.

Three workflows the pass/fail shape unlocks

1. CI gates. Pull the score in a GitHub Action and fail the build if it drops below 85. Twenty lines of YAML and a single API call. We publish a GitHub Action that does exactly this, but you can roll your own with curl.

- name: SEO checker
  run: |
    SCORE=$(curl -s -H "X-API-Key: ${{ secrets.SEO_KEY }}" \
      "https://seoscoreapi.com/audit?url=https://preview.example.com" \
      | jq '.score')
    if [ "$SCORE" -lt 85 ]; then exit 1; fi

2. Regression diffs. Store yesterday's audit JSON, run today's, diff the checks arrays. Any check that flipped pass → fail is a regression you can name. We do this in the historical tracking endpoint and it's also trivial to do client-side with two JSON blobs and a dict comparison.

3. Agent loops. An AI agent doesn't want a screenshot, it wants structured findings to act on. Hand the agent the checks array and let it decide which failures to fix in which order. See Build an AI SEO Agent for a worked example.

Why structured pass/fail beats a score-only API

A lot of "SEO score" APIs return a number and nothing else. That's not actually useful in code — you can't fix a problem you can't name. The minimum useful response for an SEO checker API is:

An overall 0–100 score (for thresholding)
A category breakdown (for routing fixes to teams)
Per-check results with stable IDs (for diffs and remediation)

SEO Score API returns all three. Every check has a stable string ID (title_length, canonical_present, og_image_dimensions) that you can match against across audits without parsing display text.

How it relates to dashboard tools

A dashboard tool — Ahrefs Site Audit, Screaming Frog, Sitebulb — is built to give a human the full picture of a site so they can prioritize. An SEO checker API is built for the moment after prioritization, when you already know what "good" looks like and want code to enforce it.

The two are complementary. Big agencies typically run a dashboard for human-driven discovery and an API for the production guardrails (CI gates, weekly client diffs, monitoring). How SEO Score API sits alongside Ahrefs and Moz goes into more detail on the split.

Getting started in five minutes

curl -H "X-API-Key: YOUR_KEY" \
  "https://seoscoreapi.com/audit?url=https://your-site.com"

That's the full first interaction. You'll get back the same response shape your CI gates and monitoring will eventually consume — which means the prototype you write today is the production code you ship tomorrow.

If you're evaluating SEO checker APIs against each other, the questions worth asking are: does it render JavaScript pages (we do, via headless Chromium)? Does it return stable check IDs (yes)? Does it have SDKs in your language (Python, Node, n8n, and a GitHub Action ship today)? And does the free tier let you actually evaluate the response shape before committing? All four of those are table stakes for a checker that's going to live in your pipeline.

Pre-Deploy SEO Gates: Catch Score Regressions Before You Ship

Aaron VanSledright — Mon, 14 Sep 2026 14:00:04 +0000

The pattern that costs teams the most SEO traffic is the one nobody can post-mortem: a regression that shipped a month ago, that nobody noticed because traffic only dipped 8%, that nobody can attribute to a specific deploy. By the time someone runs an audit, twenty commits have landed and the cause is buried.

The fix is to audit every PR before it merges and fail the gate when the score drops materially. This post walks through that gate end-to-end — what to compare, what threshold to use, and the actual GitHub Actions / GitLab CI / generic Python implementation.

What a pre-deploy SEO gate actually checks

There are three distinct comparisons worth running on a PR, in order of how strict they should be:

PR preview URL vs production. Most teams have preview deploys (Vercel, Netlify, Cloudflare Pages). Audit the preview, audit prod, fail if the gap is wider than threshold. This is the strictest, most useful check.
Preview vs last preview. If you don't ship to production from main, or you want a check on a feature branch before it touches prod, audit this branch's preview vs the previous branch's preview.
PR preview vs all-time best. Useful as a soft warning, not a hard gate — "this PR isn't bad, but the homepage was at 94 in February and you're at 89."

We'll focus on #1, which is what 90% of teams want.

The minimum viable gate

# .ci/seo-gate.py
import os, sys, requests

API_KEY = os.environ["SEOSCORE_API_KEY"]
PREVIEW_URL = os.environ["PREVIEW_URL"]   # e.g., https://pr-142-foo.vercel.app
PROD_URL = os.environ["PROD_URL"]         # e.g., https://yourdomain.com
BASE = "https://api.seoscoreapi.com"
THRESHOLD = -3.0

r = requests.post(
    f"{BASE}/compare",
    headers={"X-API-Key": API_KEY},
    json={"urls": [PREVIEW_URL, PROD_URL]},
    timeout=120,
)
r.raise_for_status()
data = r.json()

# /compare returns sites[] in submission order
preview_score = data["sites"][0]["score"]
prod_score    = data["sites"][1]["score"]
delta = preview_score - prod_score

print(f"Preview: {preview_score}  Prod: {prod_score}  Delta: {delta:+.1f}")

if delta <= THRESHOLD:
    print(f"::error::SEO regression of {delta:+.1f} points (threshold {THRESHOLD})")
    sys.exit(1)

That's the entire gate. Twenty lines. One API call (the /compare endpoint audits both sides in parallel on our side). 30 seconds wall time.

Pick a useful threshold

-3.0 is the threshold we've landed on for most teams after watching this run on real PRs for a year. It's:

Tight enough to catch real regressions. A 3-point drop is roughly "you broke a category" — typically performance from an unoptimized asset, or accessibility from a new component shipped without alt text.
Loose enough to avoid false positives. SEO Score has some run-to-run noise of ~1 point (response timing, network variance). -3.0 is comfortably outside that band.

For high-stakes pages (homepage, top landing page), tighten to -2.0. For experimental routes, loosen to -5.0. For categories you care about specifically, gate per-category:

prod_cats = data["sites"][1]["categories"]
prev_cats = data["sites"][0]["categories"]

for cat, threshold in {"performance": -4, "accessibility": -2, "seo": -3}.items():
    d = prev_cats[cat] - prod_cats[cat]
    if d <= threshold:
        print(f"::error::{cat} regressed {d:+.1f} (threshold {threshold})")
        sys.exit(1)

Per-category gates are what turn this from "the gate fails sometimes" into "the gate tells me exactly what's wrong before I open the PR."

GitHub Actions wiring

# .github/workflows/seo-gate.yml
name: SEO regression gate
on:
  deployment_status:
jobs:
  gate:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: {python-version: "3.11"}
      - run: pip install requests
      - name: Run SEO gate
        env:
          SEOSCORE_API_KEY: ${{ secrets.SEOSCORE_API_KEY }}
          PREVIEW_URL: ${{ github.event.deployment_status.target_url }}
          PROD_URL: https://yourdomain.com
        run: python .ci/seo-gate.py

The deployment_status trigger waits for Vercel/Netlify/etc. to finish building the preview, then runs the gate against the preview URL it provides. That timing matters — running on pull_request instead would audit a preview that hasn't deployed yet and either error or audit stale content.

GitLab CI and CircleCI versions look essentially identical; see the generic CI/CD post for those.

What about multi-page gates?

A single-URL gate misses regressions on routes that didn't change in this PR but were affected by a global change — a layout shift, a font swap, a navigation rewrite. The fix is to audit a list of "critical pages" in batch:

CRITICAL_PAGES = [
    "/", "/pricing", "/blog", "/docs",
    "/blog/your-top-post", "/your-top-product",
]

prev_urls = [f"{PREVIEW_URL}{p}" for p in CRITICAL_PAGES]
prod_urls = [f"{PROD_URL}{p}" for p in CRITICAL_PAGES]

prev = requests.post(f"{BASE}/audit/batch", headers=h,
                    json={"urls": prev_urls}).json()["results"]
prod = requests.post(f"{BASE}/audit/batch", headers=h,
                    json={"urls": prod_urls}).json()["results"]

failures = []
for prev_r, prod_r in zip(prev, prod):
    delta = prev_r["score"] - prod_r["score"]
    if delta <= THRESHOLD:
        failures.append((prev_r["url"], delta))

if failures:
    for url, d in failures:
        print(f"::error::{url} regressed {d:+.1f}")
    sys.exit(1)

Batch audit is paid-only — this is where the gate stops being a Free-tier experiment and starts being part of your shipping process. For a team shipping 5–10 PRs a day and auditing 8 critical pages each, that's ~2,000 audits a month, which is exactly the Pro tier ($39/mo) target.

Posting results back to the PR

The failure message in CI is fine. The team will see it. But a comment on the PR with the actual scores is much more useful — it turns the gate from "the build is red" into "the homepage went from 92 to 87 because LCP regressed by 1.2s."

gh pr comment $PR_NUMBER --body "## SEO gate
| URL | Previous | This PR | Delta |
|-----|----------|---------|-------|
| / | 92 | 87 | -5.0 ❌ |
| /pricing | 88 | 88 | 0.0 ✅ |
| /docs | 84 | 84 | 0.0 ✅ |
"

Wire that up with the GitHub CLI inside the action and you've got the full pattern. The github-actions-seo-audit post has a more elaborate version with collapsed details and per-category breakdowns.

Using `/history` instead of `/compare`

/compare is the right call for a PR gate — both sides are audited fresh, no historical data needed, works on any plan with batch access. But for a post-merge check ("did main just regress from where it was yesterday?"), the history endpoint is cheaper:

hist = requests.get(
    f"{BASE}/history?url={PROD_URL}",
    headers={"X-API-Key": API_KEY},
).json()

today = hist["history"][-1]["score"]
yesterday = hist["history"][-2]["score"]
if today - yesterday <= -3.0:
    notify_slack(f"main regressed from {yesterday} to {today}")

Run that as a scheduled job after deploys merge. It uses one audit (today's) instead of two and gives you the same answer as long as you're already auditing the URL regularly.

What this catches that humans miss

A non-exhaustive list from real PRs we've seen the gate flag:

A "loading skeleton" component that shipped without an aria-label, knocking accessibility by 4 points sitewide.
A font swap from a local woff2 to a Google Fonts CDN, regressing LCP by 800ms and tanking performance.
A new "trust banner" with three external images, all 1.2MB JPEGs that should have been ~80KB WebP.
A Markdown→HTML refactor that dropped <h2> semantics inside blog posts.
A new "share to social" widget that injected six tracking scripts before paint.

Every one of these would have shipped silently and been discovered weeks later in a quarterly audit if anyone ran one. With a PR gate, they fail the build and get fixed before merge.

Cost of the gate vs cost of the regression

Two pricing observations:

The gate costs ~10 audits per PR (one batch of critical pages × pre/post). For a team shipping 100 PRs a month, that's 1,000 audits. Basic ($15/mo) covers it.
The regression it catches costs you weeks of organic traffic to a top page. One catch pays for the next several years of Basic.

We've yet to talk to a team that turned a pre-deploy SEO gate on and then turned it off again. It's the single highest-leverage piece of API tooling for a team that ships frequently.

Getting started

Copy the script, drop it in .ci/, wire it to your deployment platform's preview hook, set the threshold to -3.0, and ship a no-op PR to verify it runs. The first time it fails on a real regression — and it will, within a month — you'll know it was worth it.

For per-category gates and history-based deltas, grab a Basic key. For multi-page batch gates on a team shipping daily, the math points at Pro.

Catching SEO Regressions in Vercel Preview Deploys

Aaron VanSledright — Mon, 07 Sep 2026 14:00:05 +0000

Vercel preview deploys are the most underused SEO QA surface in modern frontend teams. Every PR gets a unique, real URL that loads in a real browser. That's exactly the environment an SEO audit needs — and it's a few minutes of YAML away from being a hard PR check.

This post is the production setup for catching SEO regressions on Vercel previews using SEO Score API. It's a sibling of Wiring an SEO analyzer API into a Next.js build but focused on the Vercel-specific gotchas.

The shape of the workflow

Three steps:

Wait for the Vercel preview to be live (it takes 30s–3min after PR push).
Audit the preview URL with SEO Score API.
Fail the PR check if the score is below the threshold.

The first step is where most teams get it wrong on the first try. The Vercel preview URL is available in the PR comment within seconds, but the deploy isn't ready for several minutes. Audit too early and you'll audit a 404 or an in-progress build.

The workflow

.github/workflows/seo-preview.yml:

name: SEO Preview Check
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  seo:
    runs-on: ubuntu-latest
    steps:
      - name: Wait for Vercel preview to be ready
        uses: patrickedqvist/wait-for-vercel-preview@v1.3.1
        id: preview
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          max_timeout: 600  # 10 min — Next.js builds can be slow

      - name: Audit preview
        id: audit
        env:
          KEY: ${{ secrets.SEO_KEY }}
        run: |
          URL="${{ steps.preview.outputs.url }}"
          RESP=$(curl -s -H "X-API-Key: $KEY" \
            "https://seoscoreapi.com/audit?url=$URL")
          SCORE=$(echo "$RESP" | jq '.score // 0')
          echo "score=$SCORE" >> $GITHUB_OUTPUT
          echo "## SEO Score: $SCORE" >> $GITHUB_STEP_SUMMARY
          echo "$RESP" | jq -r '.priorities[] | "- \(.issue)"' >> $GITHUB_STEP_SUMMARY

      - name: Threshold check
        run: |
          [ "${{ steps.audit.outputs.score }}" -ge 85 ] || exit 1

The wait-for-vercel-preview action listens for the Vercel deployment status webhook on the PR. It returns the URL only once the preview is actually serving traffic — that's the part you can't skip.

What we learned the hard way

A few things that bit us in production on the first version:

1. Don't audit immediately. Even after Vercel reports the preview is live, the CDN propagation takes another 5–10 seconds for global routes. Insert a sleep 15 after wait-for-vercel-preview if you see intermittent 502s from the audit.

2. Branch URLs change on rebase. The Vercel preview URL incorporates the branch name and commit SHA. After a force-push, the URL changes. wait-for-vercel-preview handles this if you call it fresh in every workflow run.

3. Auth-gated previews are invisible to us. If your Vercel preview deploys are behind Vercel Authentication (paid plans default to on), SEO Score API sees the auth wall, not your app. Turn off Vercel Authentication for previews, or use Vercel's protection-bypass-for-automation token and pass it as a header — we accept a ?bypass_token query parameter.

4. The first audit cold-starts the page. Next.js with on-demand rendering means the first request to a route compiles it. The audit will include that cold-start time. If your performance score is consistently 8–10 points lower than production, this is why. Run a warmup curl $URL step before the audit step and the numbers settle.

5. Set the threshold against main, not against the score you wish you had. A gate that fails every PR teaches developers to bypass it. See Pre-Deploy SEO Gates for how to pick the right threshold.

Multi-page auditing

The example above audits one URL. Most teams want to audit a small list of routes — the ones that matter for SEO, like /, /pricing, /signup, and the top 3–5 product pages.

URLS=("$URL/" "$URL/pricing" "$URL/signup" "$URL/docs")
FAIL=0
for u in "${URLS[@]}"; do
  S=$(curl -s -H "X-API-Key: $KEY" "https://seoscoreapi.com/audit?url=$u" | jq '.score // 0')
  echo "  $u → $S"
  [ "$S" -lt 85 ] && FAIL=1
done
exit $FAIL

Four URLs × ~10 PRs/day × 22 working days = ~880 audits/month. That fits in the Basic plan ($15/mo, 1,000 audits) with margin.

Posting the report back to the PR

GitHub's STEP_SUMMARY works, but a sticky PR comment is better — same content, doesn't get buried. The marocchino/sticky-pull-request-comment action handles the dedup:

- uses: marocchino/sticky-pull-request-comment@v2
  with:
    header: seo-score
    message: |
      ### SEO Preview Score: ${{ steps.audit.outputs.score }}
      Top issues:
      ${{ steps.audit.outputs.priorities }}

That comment updates in place on every push to the PR, so the latest score is always at the top of the conversation thread. Developers actually read those.

When to skip the gate

A seo-skip PR label that makes the workflow exit 0 is a one-line addition and it dramatically improves adoption. There are legitimate cases — intentional title changes, A/B test pages, copy experiments — where the gate should be silenced for one PR. Make that explicit and the rest of the team will stop disabling the workflow file when they're under deadline pressure.

What this gives you

Three months in, the win isn't the headline number going up — it's the absence of regressions. The gate catches the accidentally-deleted <title> tag, the broken canonical, the meta description someone overwrote in a CMS migration. Those don't show up in the metrics dashboard until traffic drops weeks later. The gate catches them before the PR merges.

That's the whole case for the Vercel preview audit.

Wiring an SEO Analyzer API into a Next.js Build

Aaron VanSledright — Mon, 31 Aug 2026 14:00:04 +0000

The most useful place to run an SEO analyzer API against a Next.js app isn't production — it's the preview deploy. By the time a regression hits production, you've already shipped it. By the time you find it in production, three more PRs have landed on top.

This post is the end-to-end setup for running SEO Score API against every Vercel preview deploy of a Next.js app, with a GitHub Action that fails the PR check if the score drops below a threshold. ~30 lines of YAML and one secret.

Why preview URLs and not production

Three reasons preview-deploy auditing beats production-deploy auditing:

You can block bad changes. A failed check on a preview is a PR you don't merge. A failed check on production is an incident.
Each PR is a clean diff. The score on main is a moving target; the score delta between main and feature/new-pricing is a number you can argue about in a PR review.
JS-rendered pages need a real URL. SEO Score API renders pages in headless Chrome, which means the preview deploy needs to actually be live. Vercel previews are. Local builds usually aren't.

The Vercel side

Vercel comments the preview URL on every PR. The format is stable enough to parse:

This pull request is being deployed to Vercel.
✅ Preview: https://your-app-git-feature-branch-team.vercel.app

We're going to grab that URL via the Vercel API instead of parsing the comment — same data, more reliable.

The GitHub Actions workflow

Save this as .github/workflows/seo-check.yml:

name: SEO Check
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  seo:
    runs-on: ubuntu-latest
    steps:
      - name: Wait for Vercel preview
        id: wait
        uses: patrickedqvist/wait-for-vercel-preview@v1.3.1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          max_timeout: 300

      - name: Audit preview URL
        env:
          KEY: ${{ secrets.SEO_KEY }}
          URL: ${{ steps.wait.outputs.url }}
        run: |
          RESP=$(curl -s -H "X-API-Key: $KEY" \
            "https://seoscoreapi.com/audit?url=$URL")
          SCORE=$(echo "$RESP" | jq '.score')
          GRADE=$(echo "$RESP" | jq -r '.grade')
          echo "Score: $SCORE ($GRADE) on $URL"
          if [ "$SCORE" -lt 85 ]; then
            echo "::error::SEO score $SCORE is below threshold (85)"
            echo "$RESP" | jq '.priorities'
            exit 1
          fi

That's it. The action waits for the Vercel preview to be live (up to 5 minutes), audits it, and fails the check if the score is below 85. The failing case dumps the priorities array into the log so the PR author can see what to fix.

Setting the threshold

85 is the default we recommend, but it depends on your baseline. The right way to pick a threshold:

Run the audit against main to get your current baseline.
Set the threshold 2 points below that baseline.

If your main scores 92, threshold at 90. That way the gate fails on real regressions but tolerates the ±1 noise from network conditions and external API variance.

For sites that haven't been optimized yet (main scores 65), threshold at 65. Hold the line, then ratchet up as you improve. The pre-deploy SEO gates post has more on threshold strategy.

Auditing more than the homepage

The example above audits one URL — the preview root. Most apps have at least pricing, signup, and a handful of feature pages that matter just as much. The fix is a small bash loop:

URLS=(
  "$URL/"
  "$URL/pricing"
  "$URL/signup"
  "$URL/docs"
)
FAIL=0
for u in "${URLS[@]}"; do
  S=$(curl -s -H "X-API-Key: $KEY" "https://seoscoreapi.com/audit?url=$u" | jq '.score')
  echo "  $u → $S"
  [ "$S" -lt 85 ] && FAIL=1
done
exit $FAIL

That'll burn one audit per URL per PR. On the Basic plan ($15/mo, 1,000 audits), that comfortably covers a team shipping ~10 PRs/day audited against 3 URLs each.

What this catches that Lighthouse doesn't

Lighthouse runs in your CI by default if you use Vercel — but Lighthouse is Web Vitals first, SEO second. SEO Score API runs 80+ checks specifically about SEO: title structure, meta description presence, canonical tags, schema validity, OpenGraph completeness, internal linking, AI-readability signals, robot directives.

You can run both. They overlap maybe 10% — there's no good reason not to gate on both.

What to do when a developer's PR fails the gate

Two things help adoption:

Print the priorities array in the failure log. The default response includes a sorted list of top remediation suggestions. Show them in the GitHub check output and you've turned the gate from "no, your PR is bad" into "yes, and here's what to fix."
Allow override via PR label. Add a seo-skip label that makes the workflow exit 0. There are legitimate cases (intentional title changes, A/B test pages) where the gate should be silenced. Don't make it impossible — just make it explicit.

Both of those keep the gate from becoming the kind of CI check that everyone learns to ignore.