DEV Community: Aaron VanSledright

Build an AI SEO Agent: Automated Website Auditing with Python

Aaron VanSledright — Mon, 10 Aug 2026 14:00:03 +0000

AI agents are transforming SEO workflows. Instead of manually running audits, an AI agent can crawl your site, identify issues, prioritize fixes, and generate recommendations — all autonomously.

What is an AI SEO Agent?

An AI SEO agent is an automated program that combines structured audit data with language model reasoning to identify, prioritize, and explain SEO issues without human intervention. Rather than generating a static report, the agent interprets results and produces actionable recommendations on demand. The key distinction from a traditional script is the LLM layer: instead of hard-coded logic, the agent reasons about what the data means and what to do next.

What does the seoscoreapi Python SDK do?

The seoscoreapi Python SDK wraps the SEO Score API REST endpoints into simple function calls. It handles authentication, request formatting, and response parsing — so you call audit("https://example.com", api_key=key) and get back a structured dict with score, grade, and prioritized issue list. The SDK also exposes batch_audit() for auditing multiple URLs in a single call, and signup() for programmatically creating a free API key without visiting the dashboard.

The Architecture

An AI SEO agent uses three components: the SEO Score API to provide raw audit data (82 checks per URL on paid plans), a Python orchestration layer that loops through pages and collects results, and an LLM to interpret those results and generate human-readable recommendations. These three layers are loosely coupled — you can swap the LLM (GPT-4, Claude, Gemini) or extend the orchestration without touching the audit layer.

Manual Auditing vs. AI Agent: What Changes?

Capability	Manual workflow	AI SEO agent
Audit frequency	Weekly or monthly	Continuous or scheduled
URLs covered	5-20 by hand	500+ via batch API
Issue interpretation	Human reads raw data	LLM generates plain-English recommendations
Reporting	Manual copy-paste	Automated structured output
Alert on regressions	Check manually	Automated diff + notification
Cost per audit	Engineer time	$0-0.02 per URL via API

How do you build an AI SEO agent with Python?

Building the agent takes three steps. First, install the dependencies with pip install seoscoreapi openai. Then create the audit function: call signup("agent@yourdomain.com") to get a free API key, then pass that key and your target URL to audit(). The response includes a numeric score, letter grade, and a priorities list where each item has a severity label (critical, warning, or info) and a description of the issue. The third step is LLM analysis: pass the structured result into a prompt asking for recommendations, then call your LLM of choice to interpret the data and generate plain-English fixes.

from seoscoreapi import audit, signup
import openai

api_key = signup("agent@yourdomain.com")
result = audit("https://example.com", api_key=api_key)

prompt = f"""Analyze this SEO audit and provide 3 actionable recommendations:
Score: {result['score']}/100 ({result['grade']})
Issues: {result['priorities']}"""

response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": prompt}]
)
print(response.choices[0].message.content)

How do you automate weekly SEO audits?

To run audits on a schedule, use batch_audit() to audit an entire site in a single call, then wrap the script in a cron job or workflow tool like n8n. Pass a list of URLs — homepage, about, pricing, blog — and get back a list of structured results you can loop through. Combine with an email or Slack notification step to receive weekly score summaries and issue alerts automatically. For CI/CD pipelines, add the audit to your deploy script and fail the build if any URL drops below your target score threshold.

from seoscoreapi import batch_audit

urls = [
    "https://example.com",
    "https://example.com/about",
    "https://example.com/pricing",
    "https://example.com/blog",
]
results = batch_audit(urls, api_key=api_key)

What does the agent output after an audit?

After running an audit, the agent returns a structured response containing a numeric score (0–100), a letter grade (A+ to F), and a prioritized list of issues with severity labels (critical, warning, info). Each issue includes the check name, description, and recommended fix, making it ready to pipe directly into an LLM prompt or a downstream reporting tool.

Use Cases

Agency automation: Build an agent that audits all client sites weekly and sends reports
Content QA: Audit every new blog post before publishing to catch missing meta tags or heading issues
Competitive intelligence: Monitor competitor SEO scores daily and alert on changes
CrewAI / LangChain: Add SEO auditing as a callable tool in your AI agent framework
CI/CD quality gate: Run the agent on every deploy and fail the build if score drops below threshold
Bulk site migrations: Audit all pages before and after a migration to detect regressions
Client onboarding: Auto-generate a first-audit report for new agency clients on signup
Content freshness monitoring: Alert when a high-ranking page's SEO score drops significantly

Get Started

The free tier gives you 2 audits per day to build and test your agent. For production workloads, paid plans start at $5 per month and include batch auditing, monitoring, and up to 25,000 audits per month on the Ultra plan. No credit card is required to start — sign up with your email address and get your API key immediately.

Frequently Asked Questions

What is an AI SEO agent?

An AI SEO agent is an automated program that runs structured website audits and uses a language model to interpret results, prioritize issues, and generate actionable recommendations — removing the need for manual review at every step. The LLM layer transforms raw check data into plain-English fixes that developers and content teams can act on immediately.

What does the seoscoreapi Python SDK do?

The seoscoreapi SDK wraps the SEO Score API into simple Python function calls like audit() and batch_audit(). It handles authentication and response parsing, returning structured data with scores, grades, and issue priorities ready for downstream processing or LLM input. A signup() helper lets you programmatically create a free API key without a browser.

How do you build an AI SEO agent with Python?

Install seoscoreapi and openai via pip, call audit() with your target URL and API key, then pass the structured result — score, grade, and priorities — into an LLM prompt. The LLM interprets the data and generates specific, actionable recommendations based on detected issues. The entire setup takes under 20 lines of Python and runs from any script or scheduler.

How do you automate weekly SEO audits?

Use batch_audit() to audit multiple URLs in one call, then wrap the script in a cron job or n8n workflow to run on a schedule. Pair with a Slack or email notification step to receive weekly score summaries and issue alerts without any manual trigger. For CI/CD use, add a score threshold check to fail the pipeline when quality drops below your target.

What does the agent output after an audit?

The audit response includes a numeric score (0–100), a letter grade, and a prioritized issues list with severity labels (critical, warning, info). Each entry contains the check name, a description of the problem, and the recommended fix — structured for direct use in reports or LLM prompts. The consistent response format means the same prompt template works across every URL you audit.

Add SEO Checks to Your CI/CD Pipeline

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

Add SEO Checks to Your CI/CD Pipeline

Every deployment is a chance to accidentally break SEO. A developer removes a canonical tag, a build step strips meta descriptions, a config change adds noindex to production — and you don't find out until rankings drop weeks later. The fix is treating SEO like any other quality gate: run checks on every deployment and fail the build if something critical breaks.

Why Do SEO Checks Belong in CI/CD?

SEO regressions are invisible at deploy time. Unlike a broken API endpoint or a failing unit test, a missing <title> tag or an accidental noindex directive has no immediate error signal — it silently degrades over days or weeks as search engines recrawl and update their indexes. By the time rankings drop, the causal commit is buried under dozens of subsequent changes.

CI/CD SEO checks create the same feedback loop you have for code quality: if a deployment introduces an SEO regression, the pipeline fails, the developer sees the issue immediately, and it never reaches production.

Which Checks Matter Most in a Pipeline?

Not all 54 audit checks are equally critical at deploy time. These are the high-priority checks that justify a build failure:

Check	Why it matters	Failure threshold
Meta title	Missing or empty title tanks click-through rate	Must be present
Meta description	Direct impact on SERP snippet quality	Must be present
Canonical tag	Duplicate content and indexation issues	Must be present
Noindex directive	Accidentally blocking pages from Google	Must not be set on key pages
HTTPS	Required for ranking; marks page as insecure	Must pass
Overall score	Composite health indicator	Define your own threshold (e.g., ≥ 70)

GitHub Actions Workflow

Add this workflow to .github/workflows/seo-check.yml:

name: SEO Quality Gate

on:
  deployment_status:
  push:
    branches: [main]

jobs:
  seo-audit:
    runs-on: ubuntu-latest
    if: github.event.deployment_status.state == 'success' || github.event_name == 'push'

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install SEO Score API SDK
        run: pip install seoscoreapi

      - name: Run SEO audit
        env:
          SEO_API_KEY: ${{ secrets.SEO_API_KEY }}
          AUDIT_URL: "https://your-production-site.com"
          SCORE_THRESHOLD: "70"
        run: |
          python - <<'EOF'
          import os, sys
          from seoscoreapi import audit

          result = audit(os.environ["AUDIT_URL"], api_key=os.environ["SEO_API_KEY"])
          score = result["score"]
          grade = result["grade"]
          threshold = int(os.environ["SCORE_THRESHOLD"])

          print(f"SEO Score: {score}/100 ({grade})")

          failures = []
          checks = result.get("audit", {})

          if checks.get("meta", {}).get("title") == "fail":
              failures.append("CRITICAL: Missing meta title")
          if checks.get("meta", {}).get("description") == "fail":
              failures.append("CRITICAL: Missing meta description")
          if checks.get("meta", {}).get("canonical") == "fail":
              failures.append("CRITICAL: Missing canonical tag")
          if score < threshold:
              failures.append(f"Score {score} is below threshold {threshold}")

          if failures:
              print("\nSEO Quality Gate FAILED:")
              for f in failures:
                  print(f"  - {f}")
              sys.exit(1)
          else:
              print("SEO Quality Gate PASSED")
          EOF

Store your API key as a GitHub Actions secret: Settings > Secrets and variables > Actions > New repository secret named SEO_API_KEY.

How to Fail a Build If Score Drops Below a Threshold

The pattern above uses sys.exit(1) to signal failure to the CI runner. Choose your threshold based on your baseline:

70 — reasonable starting point for most sites
80 — appropriate for established sites where any regression is significant
Custom — run an initial audit, note your current score, then set the threshold 5–10 points below it

To track score over time, write the result to a GitHub Actions output or post it as a PR comment using the GitHub API:

import os, json, urllib.request

score = result["score"]
comment = f"SEO Score: **{score}/100** ({result['grade']})"

pr_number = os.environ.get("PR_NUMBER")
if pr_number:
    data = json.dumps({"body": comment}).encode()
    req = urllib.request.Request(
        f"https://api.github.com/repos/{os.environ['GITHUB_REPOSITORY']}/issues/{pr_number}/comments",
        data=data,
        headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}", "Content-Type": "application/json"}
    )
    urllib.request.urlopen(req)

GitLab CI Example

Add to .gitlab-ci.yml:

seo-audit:
  stage: test
  image: python:3.11-slim
  script:
    - pip install seoscoreapi
    - |
      python - <<'EOF'
      import os, sys
      from seoscoreapi import audit

      result = audit("https://your-site.com", api_key=os.environ["SEO_API_KEY"])
      print(f"Score: {result['score']}/100 ({result['grade']})")

      if result["score"] < 70:
          print(f"FAIL: Score {result['score']} is below threshold 70")
          sys.exit(1)
      print("PASS: SEO quality gate cleared")
      EOF
  variables:
    SEO_API_KEY: $SEO_API_KEY
  only:
    - main
    - merge_requests

Set SEO_API_KEY in Settings > CI/CD > Variables in your GitLab project.

Python Script for Custom Pipelines

For non-GitHub/GitLab pipelines (Jenkins, CircleCI, Bitbucket Pipelines, or a local pre-deploy hook):

#!/usr/bin/env python3
"""seo_gate.py — run before any deployment to catch SEO regressions."""

import sys
import os
from seoscoreapi import audit

AUDIT_URL = os.environ.get("AUDIT_URL", "https://your-site.com")
API_KEY = os.environ["SEO_API_KEY"]
THRESHOLD = int(os.environ.get("SCORE_THRESHOLD", "70"))

result = audit(AUDIT_URL, api_key=API_KEY)
score = result["score"]
grade = result["grade"]
priorities = result.get("priorities", [])

print(f"\nSEO Audit: {AUDIT_URL}")
print(f"Score: {score}/100 ({grade})")

critical_issues = [p for p in priorities if p["severity"] == "critical"]

if critical_issues:
    print(f"\n{len(critical_issues)} critical issue(s) found:")
    for issue in critical_issues:
        print(f"  - {issue['issue']}")

if score < THRESHOLD or critical_issues:
    print(f"\nSEO Quality Gate: FAILED")
    sys.exit(1)

print(f"\nSEO Quality Gate: PASSED")
sys.exit(0)

Run it as a pipeline step: SEO_API_KEY=your_key python seo_gate.py

Get Started

Get a free API key — 2 audits/day, no credit card required
Add the workflow YAML to your repo
Set SEO_API_KEY as a pipeline secret
Push to main and watch the quality gate run

For teams running audits on every PR across multiple environments, the Basic plan ($15/mo) gives you 1,000 audits/month at 30 RPM.

Frequently Asked Questions

Why should SEO checks run in CI/CD rather than on a schedule?

Scheduled audits tell you that something broke — CI/CD checks tell you which deployment broke it. Running checks at deploy time means you catch regressions in the same pull request that introduced them, before they ever reach production and before any search engine recrawls the affected pages.

Which SEO checks are most important to fail a build on?

Fail the build on missing meta title, missing meta description, missing canonical tag, and any noindex directive on pages that should be indexed. These are high-impact, unambiguous regressions. Use a score threshold (e.g., ≥ 70) as a secondary gate to catch broader degradation across multiple minor issues.

How do you set up the SEO audit GitHub Action?

Add a workflow file to .github/workflows/seo-check.yml with a Python step that installs seoscoreapi, runs audit() against your production URL, checks for critical failures, and calls sys.exit(1) if any are found. Store your API key as a GitHub Actions secret named SEO_API_KEY.

Does the SEO audit check a staging URL or the live site?

You can audit either. For catching regressions before they go live, point the audit at your staging or preview URL after deployment but before promoting to production. For production monitoring, audit the live URL as a post-deploy verification step.

How many API calls does a CI/CD pipeline use?

Each audit call counts as one request against your monthly quota. A team pushing to main once a day uses about 30 audits/month — well within the free tier. If you audit on every PR (e.g., 10 PRs/day), the Starter plan at $5/mo (200 audits/month) covers most teams comfortably.

SEO Quality Gates with GitHub Actions

Aaron VanSledright — Mon, 27 Jul 2026 14:00:03 +0000

A broken meta tag in one pull request can silently tank your search rankings for weeks. By the time you spot the traffic drop in Google Search Console, the damage is done. The fix is simple: treat SEO like a test suite and run it automatically on every PR.

This guide walks through a real, production-ready GitHub Actions workflow using the SEO Audit Action. By the end, you'll have a workflow that audits your deployed site, posts a score report as a PR comment, and fails the build if the score drops below your threshold.

What Does the GitHub Actions SEO Audit Do?

Here's what the workflow does on every pull request:

Waits for your preview deployment (Vercel, Netlify, Cloudflare Pages, etc.)
Runs a 28-check SEO audit against the preview URL
Posts the score, grade, and top issues as a PR comment
Blocks the merge if the score is below 80

The full audit covers meta tags, technical SEO, Open Graph, performance, and accessibility — the same checks you'd get from running curl https://seoscoreapi.com/audit?url=yoursite.com.

What Are the Prerequisites?

You need two things:

A free SEO Score API key — sign up here (takes 10 seconds, no credit card)
A preview deployment in your pipeline — any system that gives you a URL for the PR branch (Vercel, Netlify, Render, etc.)

Add your API key as a repository secret:

Settings > Secrets and variables > Actions > New repository secret

Name: SEO_SCORE_API_KEY
Value: your API key

How Do You Add It to a Workflow?

Start with the simplest version. Create .github/workflows/seo-audit.yml:

name: SEO Audit

on:
  pull_request:
    branches: [main]

jobs:
  seo:
    runs-on: ubuntu-latest
    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

That's a working quality gate in 15 lines. If the SEO score is below 80, the workflow fails and the PR can't merge (assuming you have branch protection rules enabled).

The action produces a markdown summary in the GitHub Actions UI automatically — you'll see the score, grade, issue count, and top 5 issues right in the workflow run.

How Do You Get PR Comments on Audit Results?

The summary in the Actions tab is useful, but most reviewers look at the PR conversation, not the workflow logs. Let's post the results as a PR comment:

name: SEO Audit

on:
  pull_request:
    branches: [main]

jobs:
  seo:
    runs-on: ubuntu-latest
    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: Comment on PR
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const score = '${{ steps.seo.outputs.score }}';
            const grade = '${{ steps.seo.outputs.grade }}';
            const issues = '${{ steps.seo.outputs.issues }}';
            const reportUrl = '${{ steps.seo.outputs.report-url }}';
            const passed = parseInt(score) >= 80;

            const body = [
              `## SEO Audit Results`,
              ``,
              `| Metric | Value |`,
              `|--------|-------|`,
              `| Score | **${score}/100** |`,
              `| Grade | **${grade}** |`,
              `| Issues | ${issues} |`,
              `| Threshold | 80 |`,
              `| Status | ${passed ? 'Passed' : 'Failed'} |`,
              ``,
              `[View Full Report](${reportUrl})`,
            ].join('\n');

            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body
            });

The if: always() is important — it ensures the comment is posted even when the audit step fails due to a low score. Without it, a failing score would skip the comment step and you'd have to dig into the logs to find out what went wrong.

Real-World Example: Vercel Preview Deployments

Most teams don't audit a static production URL — they audit the preview deployment that Vercel (or Netlify, etc.) creates for each PR. Here's how to wire that up:

name: SEO Audit on Preview

on:
  pull_request:
    branches: [main]
    paths:
      - '**.html'
      - '**.jsx'
      - '**.tsx'
      - '**.vue'
      - '**.svelte'
      - 'content/**'
      - 'public/**'

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

      - name: SEO Audit
        id: seo
        uses: SeoScoreAPI/seo-audit-action@v1
        with:
          url: ${{ steps.preview.outputs.url }}
          api-key: ${{ secrets.SEO_SCORE_API_KEY }}
          threshold: 80

      - name: Comment on PR
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const score = '${{ steps.seo.outputs.score }}';
            const grade = '${{ steps.seo.outputs.grade }}';
            const issues = '${{ steps.seo.outputs.issues }}';
            const reportUrl = '${{ steps.seo.outputs.report-url }}';
            const previewUrl = '${{ steps.preview.outputs.url }}';
            const passed = parseInt(score) >= 80;

            const emoji = passed ? '✅' : '❌';

            const body = [
              `## ${emoji} SEO Audit`,
              ``,
              `Audited: ${previewUrl}`,
              ``,
              `| Metric | Value |`,
              `|--------|-------|`,
              `| Score | **${score}/100** |`,
              `| Grade | **${grade}** |`,
              `| Issues | ${issues} |`,
              `| Threshold | 80 |`,
              ``,
              `[Full Report](${reportUrl})`,
            ].join('\n');

            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body
            });

Three things worth noting about this version:

Path filters — the paths block ensures the audit only runs when files that affect SEO are changed. Backend-only PRs (API routes, database migrations, config changes) skip the audit entirely. This is important because audits cost API calls, and you don't want to burn them on changes that can't affect your SEO score.

Preview URL — instead of hardcoding a URL, we pull it from the Vercel preview deployment. Every PR gets its own preview URL, so you're auditing the actual changes in that PR, not the current production site.

Timeout — max_timeout: 300 gives Vercel 5 minutes to deploy. Adjust this based on your build times.

Netlify Variant

If you're on Netlify instead of Vercel, swap the preview step:

      - name: Wait for Netlify Preview
        uses: jakepartusch/wait-for-netlify-action@v1.4
        id: preview
        with:
          site_name: "your-netlify-site"
          max_timeout: 300

The rest of the workflow stays identical — just reference ${{ steps.preview.outputs.url }}.

Multi-Page Audits

For sites where SEO matters on more than one page, use a matrix strategy to audit multiple routes:

jobs:
  seo:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        path: ['/', '/pricing', '/blog', '/docs']
    steps:
      - name: SEO Audit - ${{ matrix.path }}
        id: seo
        uses: SeoScoreAPI/seo-audit-action@v1
        with:
          url: "https://your-site.com${{ matrix.path }}"
          api-key: ${{ secrets.SEO_SCORE_API_KEY }}
          threshold: 80

This runs 4 parallel audits — one per page. If any page drops below 80, that specific job fails. You can see exactly which page regressed in the Actions UI.

For larger sites (10+ pages), use the batch audit endpoint with a script step instead of the matrix approach to use fewer API calls.

How Do You Set Up Branch Protection?

The workflow only blocks merges if you configure branch protection:

Go to Settings > Branches > Branch protection rules
Add a rule for main
Check Require status checks to pass before merging
Search for and add the SEO Audit check

Now any PR where the SEO score drops below your threshold literally cannot be merged until the issues are fixed.

Choosing Your Threshold

Threshold	Best For
90	Marketing sites, landing pages where SEO directly drives revenue
80	Most production sites — catches real issues without false positives
70	Apps with some public-facing pages where SEO is secondary
60	Internal tools with minimal SEO requirements

Start at 70 if your site has existing issues, then ratchet up to 80 once the team has fixed the backlog. Don't start at 90 — you'll frustrate developers with failures on day one and they'll disable the check.

Which Plans Support CI/CD Use?

The free tier gives you 2 audits/day, which works for solo projects with a couple PRs per week. For teams:

Plan	Audits/mo	Price	Good For
Starter	200	$5/mo	Small team, 1-2 PRs/day
Basic	1,000	$15/mo	Active team, multi-page audits
Pro	5,000	$39/mo	Multiple repos, matrix audits

All paid plans support CI/CD use. The free tier is sufficient for personal projects; Starter or above is recommended for active teams. Sign up free and upgrade when your PR volume outgrows the free tier.

The Complete Workflow

Here's the full production-ready workflow with all the pieces — preview deployment, PR comments, path filtering, and the quality gate:

name: SEO Quality Gate

on:
  pull_request:
    branches: [main]
    paths:
      - '**.html'
      - '**.jsx'
      - '**.tsx'
      - '**.vue'
      - '**.svelte'
      - 'content/**'
      - 'public/**'

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

      - name: Run SEO Audit
        id: seo
        uses: SeoScoreAPI/seo-audit-action@v1
        with:
          url: ${{ steps.preview.outputs.url }}
          api-key: ${{ secrets.SEO_SCORE_API_KEY }}
          threshold: 80

      - name: Post Results to PR
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const score = '${{ steps.seo.outputs.score }}';
            const grade = '${{ steps.seo.outputs.grade }}';
            const issues = '${{ steps.seo.outputs.issues }}';
            const reportUrl = '${{ steps.seo.outputs.report-url }}';
            const previewUrl = '${{ steps.preview.outputs.url }}';
            const passed = parseInt(score) >= 80;

            const emoji = passed ? '✅' : '❌';
            const status = passed ? 'Passed' : 'Failed — fix issues before merging';

            const body = [
              `## ${emoji} SEO Audit`,
              ``,
              `**${status}**`,
              ``,
              `| Metric | Value |`,
              `|--------|-------|`,
              `| Preview | ${previewUrl} |`,
              `| Score | **${score}/100** |`,
              `| Grade | **${grade}** |`,
              `| Issues | ${issues} |`,
              `| Threshold | 80 |`,
              ``,
              `[View Full Report →](${reportUrl})`,
            ].join('\n');

            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body
            });

Copy that into .github/workflows/seo-audit.yml, add your SEO_SCORE_API_KEY secret, enable branch protection, and you have an automated SEO quality gate protecting your site from regressions on every pull request.

Frequently Asked Questions

What does the GitHub Actions SEO Audit action do?

The SEO Audit Action runs a 28-check SEO audit against your site on every pull request. It checks meta tags, technical SEO, Open Graph, performance, and accessibility, then posts a score and grade as a PR comment and fails the build if the score drops below your configured threshold.

How do you add the SEO audit to a GitHub Actions workflow?

Create .github/workflows/seo-audit.yml, add the SeoScoreAPI/seo-audit-action@v1 step with your url, api-key (stored as a repository secret), and a threshold value. The action installs automatically — no additional dependencies or setup scripts required.

What score threshold triggers a build failure?

The threshold is configurable via the threshold input parameter. The default recommendation is 80 for most production sites. Scores below your threshold fail the workflow step, which blocks the PR from merging when branch protection is enabled. Start at 70 for sites with existing issues, then raise it over time.

How do PR comments with audit results work?

Add a second step using actions/github-script@v7 with if: always(). It reads the score, grade, issues, and report-url outputs from the audit step and posts them as a formatted comment on the pull request. The if: always() ensures the comment appears even when the audit fails.

Which plans support CI/CD use with GitHub Actions?

All plans, including the free tier (2 audits/day), support CI/CD use. The free tier works for solo projects with a few PRs per week. For active teams, the Starter plan ($5/mo, 200 audits/month) or Basic plan ($15/mo, 1,000 audits/month) is recommended depending on PR volume and multi-page audit needs.

Node SDK 1.3: Run SEO Audits, Track Trends, and Get Slack Alerts from Any Node Project

Aaron VanSledright — Mon, 20 Jul 2026 14:00:05 +0000

The Node.js client for SEO Score API is at 1.3.0 on npm. It mirrors the Python release we shipped at the same time: a new compare() function for side-by-side URL diffs, full history() and historyDomains() timeseries access, and webhook alerts on the monitor system (Slack-formatted automatically when you point it at an incoming webhook).

Install or upgrade with:

npm install seoscoreapi@latest

Or with pnpm/yarn — same name, no native dependencies, runs anywhere Node 18+ has fetch available.

What's new in 1.3

Function	Endpoint	Tier
`compare(urls, apiKey)`	`POST /compare`	Basic+
`history(url, apiKey, opts)`	`GET /history`	Starter+
`historyDomains(apiKey)`	`GET /history/domains`	Starter+
`addMonitor(url, apiKey, { webhookUrl, alertThreshold })`	`POST /monitors`	Paid

addMonitor is backwards compatible — the legacy addMonitor(url, apiKey, "weekly") form still works, but if you want webhooks you'll pass an options object instead.

1. Compare your page against 2–4 competitors in one call

compare() accepts 2–5 URLs and returns each one's score plus a diff block telling you who is ahead, per category, per pair:

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

const result = await compare(
  [
    "https://acme.com/pricing",
    "https://competitor-a.com/pricing",
    "https://competitor-b.com/pricing",
  ],
  process.env.SEOSCORE_API_KEY,
);

for (const url of result.urls) {
  console.log(`${url.url}: ${url.score} (${url.grade})`);
}

for (const gap of result.diff.category_gaps) {
  console.log(`${gap.category}: leader ${gap.leader} (+${gap.gap.toFixed(1)})`);
}

This one's Basic plan ($15/mo) and up. It's the call we use to power the agency-style "where do we stand?" dashboards customers have been building on top of the API.

2. Pull historical scores for any URL

If your account has been running audits on a paid plan, every audit's full score breakdown is already in our database. history() returns the full timeseries plus a summary block:

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

const data = await history(
  "https://acme.com",
  process.env.SEOSCORE_API_KEY,
  { limit: 90 },
);

console.log(`${data.count} audits tracked`);
console.log(`First: ${data.summary.first_score}`);
console.log(`Latest: ${data.summary.latest_score}`);
console.log(`Total delta: ${data.summary.total_delta.toFixed(1)}`);

Retention windows are tied to your tier — Starter sees 30 days, Basic 90, Pro a year, Ultra unlimited. The deeper write-up on what's in the history block is in the historical comparison post.

3. One-shot view of every domain you've audited

historyDomains() returns one row per domain on your key, with the latest score and a 30-day trend:

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

const domains = await historyDomains(process.env.SEOSCORE_API_KEY);
domains.sort((a, b) => (a.trend_30d ?? 0) - (b.trend_30d ?? 0));

console.log("Worst trends this month:");
for (const d of domains.slice(0, 10)) {
  const arrow = (d.trend_30d ?? 0) < 0 ? "↓" : "↑";
  console.log(`  ${d.domain.padEnd(40)} ${d.latest_score} ${arrow}${Math.abs(d.trend_30d ?? 0).toFixed(1)}`);
}

Single API call, one row per domain. Use it for a Slack digest, an agency dashboard, or to feed an LLM that's writing a quarterly recap.

4. Get Slack alerts on score drops

addMonitor() now takes a webhookUrl and alertThreshold:

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

await addMonitor(
  "https://acme.com",
  process.env.SEOSCORE_API_KEY,
  {
    frequency: "daily",
    webhookUrl: "https://hooks.slack.com/services/T0/B0/xxxx",
    alertThreshold: 5, // alert when the score drops 5+ points
  },
);

If the webhook URL points at hooks.slack.com, the payload is auto-formatted as Block Kit so it renders cleanly. Any other https endpoint gets the raw event JSON — wire it into PagerDuty, Discord, n8n, or your own service.

Three places to drop this into a Node project

Express middleware that runs an SEO audit on demand

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

const app = express();

app.get("/seo-check", async (req, res) => {
  const result = await audit(req.query.url, process.env.SEOSCORE_API_KEY);
  res.json({
    score: result.score,
    grade: result.grade,
    delta: result.history?.delta,
    top_issues: (result.priorities || []).slice(0, 3),
  });
});

app.listen(3000);

The result.history.delta field is what makes this useful in production: every audit response on a paid plan tells you whether the score moved since last time and by how much.

Next.js API route for an internal dashboard

// app/api/seo-snapshot/route.js
import { historyDomains } from "seoscoreapi";

export async function GET() {
  const domains = await historyDomains(process.env.SEOSCORE_API_KEY);
  return Response.json({
    domains: domains.map((d) => ({
      domain: d.domain,
      score: d.latest_score,
      grade: d.latest_grade,
      trend_30d: d.trend_30d,
    })),
  });
}

That's the entire backend for an internal "all our brands at a glance" page.

Stand-alone weekly CLI you run from cron

#!/usr/bin/env node
const { historyDomains } = require("seoscoreapi");

const domains = await historyDomains(process.env.SEOSCORE_API_KEY);
const dropped = domains.filter((d) => (d.trend_30d ?? 0) <= -2.0);

if (dropped.length === 0) {
  console.log("All domains stable.");
  process.exit(0);
}

console.log(`${dropped.length} domains down 2+ points:`);
for (const d of dropped) {
  console.log(`  ${d.domain}: ${d.latest_score} (${d.trend_30d.toFixed(1)} 30d)`);
}
process.exit(1);

Pipe the output to email or wire it to a Slack incoming webhook, schedule it weekly with cron or a CI pipeline, and you've got an automated Monday-morning report.

Upgrading from 1.2

Strict additive update. addMonitor() accepts the new options object form or the legacy (url, apiKey, "daily") string form, so existing code keeps working. The new functions are pure additions.

npm install seoscoreapi@latest

The full reference is in the README and at /docs. If you don't have a key yet, grab a free one or start on Starter for $5/mo.

Python SDK 1.3: Historical Trends, URL Comparisons, and Slack Alerts in Three Lines Each

Aaron VanSledright — Mon, 13 Jul 2026 14:00:03 +0000

The Python client for SEO Score API hit 1.3.0 today. It picks up everything we shipped through the latest sprint: side-by-side URL comparison, the /history and /history/domains endpoints, and webhook alerts (Slack-formatted by default) on the monitor system.

If you already have seoscoreapi installed, upgrade with:

pip install --upgrade seoscoreapi

Then the rest of this post is a tour of what the new functions actually do.

What's in 1.3

Function	Endpoint	Tier
`compare(urls, api_key)`	`POST /compare`	Basic+
`history(url, api_key, limit=100, since=None)`	`GET /history`	Starter+
`history_domains(api_key)`	`GET /history/domains`	Starter+
`add_monitor(..., webhook_url, alert_threshold)`	`POST /monitors`	Paid

competitive_audit() and report_url() were already in 1.2 — they're listed here for completeness because they pair well with the new history functions.

1. Compare your page against competitors in one call

Before 1.3, doing a head-to-head comparison meant calling /audit for each URL and computing diffs yourself. Now compare() does it server-side and returns a structured diff block:

import os
from seoscoreapi import compare

result = compare(
    [
        "https://acme.com/pricing",
        "https://competitor-a.com/pricing",
        "https://competitor-b.com/pricing",
    ],
    api_key=os.environ["SEOSCORE_API_KEY"],
)

for url_data in result["urls"]:
    print(f"{url_data['url']}: {url_data['score']} ({url_data['grade']})")

print("\nGap analysis:")
for entry in result["diff"]["category_gaps"]:
    print(f"  {entry['category']}: leader is {entry['leader']} (+{entry['gap']:.1f})")

compare() accepts 2–5 URLs in a single request and returns each URL's full audit, plus the diff object that tells you who is ahead in every category. It's Basic plan ($15/mo) and up.

This is the hook agency people have been asking for — drop it into a Streamlit or Slack-bot and you've got a "where do we stand against the top 3 competitors?" tool in 30 lines.

2. Pull the full audit history for any URL

If you've been auditing a URL on a paid plan, every audit's score breakdown is already in our database. history() returns the full timeseries plus a summary block:

from seoscoreapi import history

data = history("https://acme.com", api_key=os.environ["SEOSCORE_API_KEY"])

print(f"Tracked: {data['count']} audits")
print(f"  First: {data['summary']['first_score']}")
print(f"  Latest: {data['summary']['latest_score']}")
print(f"  Total delta: {data['summary']['total_delta']:+.1f}")
print(f"  Min/Max: {data['summary']['min_score']}/{data['summary']['max_score']}")

# Plot it
import matplotlib.pyplot as plt
ts = [p["timestamp"] for p in data["history"]]
scores = [p["score"] for p in data["history"]]
plt.plot(ts, scores)
plt.savefig("acme-trend.png")

history() accepts limit and since parameters if you want to scope the response. The retention windows are tied to your tier:

Plan	Retention
Starter ($5/mo)	30 days
Basic ($15/mo)	90 days
Pro ($39/mo)	1 year
Ultra ($99/mo)	Unlimited

For a deeper write-up on what's in the history block, see the historical comparison post.

3. Get a one-shot view of every domain you track

history_domains() is the "all your stuff at a glance" call:

from seoscoreapi import history_domains

domains = history_domains(api_key=os.environ["SEOSCORE_API_KEY"])

# Sort by 30-day trend, worst first
domains.sort(key=lambda d: d.get("trend_30d", 0))

for d in domains[:10]:
    arrow = "↓" if d.get("trend_30d", 0) < 0 else "↑"
    print(f"{d['domain']:40} {d['latest_score']:>3} {arrow}{abs(d.get('trend_30d', 0)):.1f}")

One call, one row per domain you've ever audited. Use it for an agency-wide "who needs attention this week?" dashboard or a Slack digest.

4. Get alerted in Slack when a score drops

add_monitor() now takes webhook_url and alert_threshold. If the webhook URL is a Slack incoming-webhook, the payload is auto-formatted as Block Kit:

from seoscoreapi import add_monitor

add_monitor(
    "https://acme.com",
    api_key=os.environ["SEOSCORE_API_KEY"],
    frequency="daily",
    webhook_url="https://hooks.slack.com/services/T0/B0/xxxx",
    alert_threshold=5,  # alert when the score drops 5+ points
)

A 5-point drop on Acme's homepage now pings your #seo-alerts channel within minutes of the next scheduled audit run. Other https endpoints get the raw event JSON, so you can route alerts into PagerDuty, Discord, your own SIEM — anything that takes a webhook.

The alert_threshold is in score points, not percent. Five points is a reasonable starting value: small enough to catch real regressions, large enough to ignore the kind of noise that comes from a slow Core Web Vitals reading on a single audit.

A complete worked example: the 30-line agency monitor

Putting it together, here's the entire script we run for a small in-house team. It uses every new function in 1.3:

import os
from seoscoreapi import history_domains, history, compare

API_KEY = os.environ["SEOSCORE_API_KEY"]

# 1. Find URLs that dropped 2+ points this month
domains = history_domains(API_KEY)
dropped = [d for d in domains if d.get("trend_30d", 0) <= -2.0]
dropped.sort(key=lambda d: d["trend_30d"])

print(f"## {len(dropped)} URLs to investigate\n")

# 2. For each, pull the timeseries to see when the drop happened
for d in dropped[:5]:
    h = history(f"https://{d['domain']}", API_KEY, limit=20)
    points = h["history"][-5:]
    print(f"### {d['domain']}")
    for p in points:
        print(f"  {int(p['timestamp'])}: {p['score']}")

# 3. Compare your worst one against two competitors
worst = dropped[0]
result = compare(
    [
        f"https://{worst['domain']}",
        "https://competitor-a.com",
        "https://competitor-b.com",
    ],
    API_KEY,
)
for u in result["urls"]:
    print(f"\n{u['url']}: {u['score']} ({u['grade']})")

That's a daily report that used to take a half-day in spreadsheets, in 30 lines, billable as a fixed-price retainer add-on. The full SDK reference is in the README and the auto-generated API docs.

Upgrading from 1.2

Nothing breaks. add_monitor() gets two new optional kwargs, but every existing call works as-is. The new functions (compare, history, history_domains) were either new in this release or added in 1.2 — if you've been on 1.2 already, this is a strict additive update.

pip install --upgrade seoscoreapi

If you don't have a key yet, grab a free one or start on Starter for $5/mo to get historical tracking on day one.

SEO Audit API for Developers: Complete Guide

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

SEO Audit API for Developers: Complete Guide

The SEO Score API is a REST API that runs a full technical SEO audit on any URL and returns a structured JSON response with a score, grade, and prioritized list of issues — covering meta tags, performance, accessibility, structured data, and AI readiness in a single call. For the endpoint overview, response shape, and full check list, see the SEO audit API reference; this guide walks through integrating it as a developer.

What is the SEO Score API?

The SEO Score API performs instant, headless-browser-backed audits across 54 checks and returns structured results in under 5 seconds. There's no scraping to manage, no Playwright setup required on your end, and no rate-limit gymnastics — just a single GET request per URL. It's designed for developers who want to add SEO intelligence to their applications, dashboards, or CI/CD pipelines without building the audit engine themselves.

How does authentication work?

Every request must include your API key in the X-API-Key header:

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

You can get a free key (2 audits/day) at seoscoreapi.com/#signup — no credit card required. Paid plans start at $5/mo for 200 audits/month.

The /audit Endpoint

GET /audit?url={url}

Response example

{
  "url": "https://example.com",
  "score": 74,
  "grade": "B",
  "priorities": [
    {
      "severity": "critical",
      "issue": "Missing meta description",
      "recommendation": "Add a 120–165 character meta description tag."
    },
    {
      "severity": "warning",
      "issue": "Page load time 2.8s",
      "recommendation": "Optimize images and enable compression to get below 2s."
    }
  ],
  "audit": {
    "meta": { "title": "pass", "description": "fail", "canonical": "pass" },
    "performance": { "load_time_ms": 2800, "compression": "pass" },
    "accessibility": { "lang": "pass", "alt_tags": "warning" },
    "structured_data": { "json_ld": "pass", "og_tags": "pass" },
    "ai_readiness": { "robots_ai": "fail", "llms_txt": "fail" }
  }
}

Python SDK Example

Install the SDK:

pip install seoscoreapi

Run an audit in 5 lines:

from seoscoreapi import audit, signup

api_key = signup("you@example.com")  # one-time free key creation
result = audit("https://example.com", api_key=api_key)
print(f"Score: {result['score']}/100 ({result['grade']})")

Iterate over issues:

for issue in result["priorities"]:
    print(f"[{issue['severity'].upper()}] {issue['issue']}")
    print(f"  Fix: {issue['recommendation']}")

JavaScript / curl Examples

Node.js (fetch):

const response = await fetch(
  "https://seoscoreapi.com/audit?url=https://example.com",
  { headers: { "X-API-Key": "YOUR_KEY_HERE" } }
);
const data = await response.json();
console.log(`Score: ${data.score}/100 (${data.grade})`);

curl with jq:

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

The 5 Audit Categories

Category	What it covers	Example checks
Meta	On-page SEO fundamentals	Title tag, meta description, canonical, robots meta
Performance	Speed and delivery signals	Load time, compression, render-blocking scripts
Accessibility	Usability and standards	`lang` attribute, image alt text, heading structure
Structured Data	Rich result eligibility	JSON-LD presence, Open Graph tags, schema types
AI Readiness	LLM discoverability	AI bot access in robots.txt, llms.txt, SSR, fact density

On paid plans (Starter and above), three additional scoring dimensions are returned: SXO (search experience), AEO (answer engine eligibility), and AIO (AI optimization) — each with their own score, grade, and check breakdown.

Error Handling

Status	Meaning	Action
`401 Unauthorized`	Missing or invalid API key	Check the `X-API-Key` header value
`422 Unprocessable Entity`	Invalid or missing URL parameter	Ensure `url` is a valid, fully-qualified URL
`429 Too Many Requests`	Rate limit or daily quota exceeded	Back off and retry, or upgrade your plan

All error responses include a JSON body with a detail field explaining the specific problem.

Get Started

Free key — Sign up here for 2 audits/day, no credit card
Python SDK — pip install seoscoreapi
npm SDK — npm install seoscoreapi
Paid plans — start at $5/mo for 200 audits/month at seoscoreapi.com/#pricing

Frequently Asked Questions

What is the SEO Score API?

The SEO Score API is a REST API that runs instant technical SEO audits on any URL using a headless browser. It returns a structured JSON response with a 0–100 score, letter grade, and prioritized issue list covering 54 checks across meta, performance, accessibility, structured data, and AI readiness.

How do you authenticate with the SEO Score API?

Authentication uses an X-API-Key header on every request. Get a free key at seoscoreapi.com — it gives you 2 audits per day with no credit card required. Paid plans starting at $5/mo increase limits to 200–25,000 audits per month.

What does the /audit endpoint return?

The /audit endpoint returns a JSON object with score (0–100), grade (A+ to F), priorities (an array of issues with severity and recommended fix), and a full audit object broken into five categories. Paid plans also include sxo, aeo, and aio scoring objects.

How do you handle 429 rate limit errors?

A 429 response means you've hit either your per-minute rate limit (RPM) or your daily/monthly quota. Implement exponential backoff and retry after the interval suggested in the response. For sustained high-volume needs, upgrade to a higher plan — Pro allows 60 RPM and 5,000 audits/month.

Is there a Python or JavaScript SDK?

Yes. Install the Python SDK with pip install seoscoreapi and the JavaScript SDK with npm install seoscoreapi. Both wrap the REST API with typed function calls, handle authentication, and return parsed response objects — no raw HTTP requests needed for common operations.

SEO audits in Claude + Cursor: our new MCP server

Aaron VanSledright — Mon, 29 Jun 2026 14:00:03 +0000

SEO audits in Claude + Cursor: our new MCP server

We just shipped an official Model Context Protocol server. Install it once and Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-aware AI tool gets direct access to:

Full SEO audits (audit, batch_audit)
Your monitoring (add_monitor, list_monitors)
Audit-score history (history, history_domains)
Public report URLs (report_url)
Plan and usage (usage)
Observed backlinks (backlinks, Basic plan and up)

That's nine tools your AI can reach for the moment you ask "audit this URL" or "what backlinks point at my-startup.com?"

Why MCP matters for SEO

Most AI tools today guess at SEO. The model has a fuzzy idea of what a good page looks like, an even fuzzier idea of how Google ranks anything in 2026, and zero idea what your specific page actually scores. So you get advice like "make sure your meta description is between 150 and 160 characters" — true, generic, and unverifiable.

MCP changes the shape of that conversation. The AI doesn't need to guess; it can call our scoring engine directly. The same 82-check audit your CI pipeline runs is now one tool call away from any prompt.

The difference in practice:

Before MCP

"Hey Claude, can you audit my site?"
"I can't access URLs directly, but here are some general tips: make sure your title tags are 50-60 characters, write descriptive meta descriptions..."

After MCP

"Hey Claude, can you audit my site?"
(Claude calls the audit tool against https://seoscoreapi.com.)
"Your site scores 97.9 / A+. The only category with a flag is meta — your homepage description is 154 chars, well within range. AI readability scores 96/A+. The top priority would be... actually you have zero priorities right now. You're clean."

That's not a parlor trick. That's grounded answer-engine output, and it's exactly the kind of answer LLMs are starting to be measured on.

Install in 30 seconds

npx -y seoscoreapi-mcp

Or, in your AI client's config:

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

Get a free API key. The free tier covers 2 audits per day with no card required — enough to wire up the MCP server and run your first batch.

Full setup instructions for Claude Desktop, Claude Code, Cursor, and Windsurf are in the README.

What you can ask once it's installed

Real prompts that route through the MCP tools without you specifying which one:

"Audit https://stripe.com and tell me the top 3 things to fix."

"Compare the AI readability scores of stripe.com, square.com, and adyen.com."

"What backlinks have we observed pointing at my-startup.com?"

"Show me the score history for our marketing site over the last 30 days."

"Are any of my monitored URLs trending down?"

The AI picks the right tool. You don't.

The `backlinks` tool deserves its own paragraph

This is unique to SEO Score API. Every audit our customers run contributes to a growing backlink graph: external links observed on each audited page get persisted into a public dataset. The backlinks tool surfaces that dataset for any domain, with an explicit data_caveat in every response.

It is not a comprehensive backlink index — Ahrefs crawls 8 billion pages a day and we don't, and we say so. It is honest, audit-fed, and grows with usage. For "show me referring pages we have actually seen," it works exactly the way you'd want.

> What backlinks does SEO Score API see pointing to stripe.com?

(via `backlinks` tool)

stripe.com:
  total observations: 142
  referring domains: 38
  top referring: docs.stripe.com (24), github.com (18), ...
  data_caveat: Backlinks observed during SEO Score API audits.
  Not exhaustive — coverage grows over time.

No competitor with our pricing offers anything like this, because no competitor has the audit volume we do feeding the graph.

Why we're shipping this now

Two reasons.

One: every developer audience we care about is moving into MCP-aware tools. Claude Desktop has it, Claude Code has it, Cursor has it, Windsurf has it, the OpenAI agents framework has it. If our API isn't reachable from the place customers actually do their work in 2026, we're invisible — even when we're the right answer.

Two: MCP is the cleanest possible packaging of the API. There's no SDK to learn, no auth dance to script, no batching to build. The user types a question, the AI picks the tool, the API answers. Friction approaches zero. That's the kind of leverage we want.

We have official Python and Node SDKs. We have a GitHub Action for CI. We have an n8n community node. The MCP server is the same idea — meet developers where they already are — pointed at AI clients instead of CI runners.

Source + license

seoscoreapi-mcp is MIT-licensed and open source. The whole server is one file you can read in five minutes:

https://github.com/avansledright/seoscoreapi.com/tree/main/sdks/mcp

If you build something on top of it, send us the link. We'll feature interesting integrations on the blog.

Try it

Get a free API key — 30 seconds, no card.
Add the MCP config to your AI client of choice.
Restart the client.
Ask: "Audit https://example.com."

That is the entire onboarding.

What We're Seeing After 8,000 SEO Audits

Aaron VanSledright — Thu, 25 Jun 2026 19:00:13 +0000

When you operate an SEO audit API, you end up with a strange vantage point. You don't see the full web — you see whatever sites people are bothering to check. That sample is biased: agencies running their client roster, developers wiring up CI checks, builders auditing their own pages. It is not a random crawl of the internet.

But it is a fairly honest cross-section of the sites that someone, somewhere, cared enough about to audit. And after running roughly 8,000 audits, the patterns are remarkably consistent.

Here's what we're seeing.

Most sites land in the same narrow band

The single most surprising finding wasn't about a specific issue. It was about how little spread there is in scores.

Average score: ~73 / 100
Median: ~73
~90% of all audits land between 70 and 79

Roughly 8% score 80 or higher. Almost nothing scores below 60. The web isn't bimodal between "great" and "terrible" sites — it's a giant middle. Most sites are doing the basics, missing the same handful of intermediate things, and getting a soft B as a result.

That tight clustering matters strategically: if you're operating in this range, the work to move from a 73 to an 85 is mostly the same five fixes applied to almost every site we see.

The five issues that show up almost everywhere

When we tally the top-five priority issues flagged on each audit, five items dominate — each appearing on roughly 9 out of 10 audits we've run:

Issue	Share of audits flagging it
No structured data (schema.org)	~94%
No sitemap.xml	~93%
Missing meta description	~92%
No canonical tag	~92%
Thin content on the audited page	~88%

These aren't exotic problems. They're not algorithm-update edge cases. They're the items every SEO checklist has had on it for a decade. And yet they're nearly universal.

A few notes on what's going on under each:

Structured data isn't optional anymore. Google's AI Overviews, ChatGPT search citations, and Perplexity's source picker all lean on schema to disambiguate what a page is about. A site without Article, Organization, or Product schema is asking AI search to guess.
Sitemap.xml is the cheapest crawl-budget signal you can give a search engine, and most sites still don't have one, or have one that isn't referenced from robots.txt.
Meta description isn't a ranking factor — but it's a click-through factor, which is a downstream ranking factor. Letting Google auto-generate it from page content is leaving CTR on the table.
Canonical tags are the single most reliable way to prevent self-inflicted duplicate-content problems. Most sites still don't set them.
Thin content here usually means the audited URL itself was light on text — landing pages, footer-linked utility pages, "about" stubs. Worth deciding whether those pages should be indexed at all.

Performance is not where most sites are losing

This one cut against my expectations. The performance category — request timing, response size, a basic look at render readiness — averages around 97 / 100 across all audits.

The "your site is slow" narrative is mostly outdated for the modern web. Cloudflare, Vercel, Netlify, and standard CDN setups have made fast-by-default the norm. The sites failing on performance are now the exception, not the rule.

Where they still exist, the failure mode is almost always the same: a heavy WordPress install with a page-builder theme stacking 30+ render-blocking scripts. The fix isn't tuning — it's a different stack.

The social / AI surface area is broken almost everywhere

Inversely, the social score average sits at around 41 / 100. This is the metadata that controls how a page renders when shared in Slack, LinkedIn, iMessage, X, Facebook — and increasingly, how AI search engines build their preview cards.

The pattern: sites have some OpenGraph tags (often whatever the CMS auto-generates), but they're missing og:image, twitter:card, structured author data, and consistent canonical URLs. The result is that when a link gets shared — which is increasingly the dominant traffic source for content sites — the unfurl looks like a 2012 Reddit post.

This is the highest ROI fix in the whole list, because it's the one your traffic source actually sees first.

What the numbers don't tell you

A few honest caveats, because the data has limits:

The sample skews toward sites being audited. Sites run through an audit API are disproportionately professional/SaaS/agency clients. Genuinely abandoned or amateur sites are underrepresented.
Repeated audits of the same page count separately. If a developer wires up an audit into CI, that one URL gets audited dozens of times. The aggregate is "audits run," not "unique sites."
Top-5 priorities is a per-audit ranking. An issue showing up in 92% of audits' top 5 doesn't mean 92% of sites have it — it means it's almost always severe enough to be flagged in the top 5 when present.

So treat the numbers as directional rather than demographic. They tell you what shows up over and over when professionals look at the sites they care about. That's still useful.

The actionable read

If you're prioritizing SEO work in 2026, the data suggests a clear order:

Ship structured data first. This is your AI search insurance policy.
Fix social/OG metadata. Highest visibility per hour of effort.
Audit canonical and sitemap setup. Cheapest "crawl hygiene" wins available.
Stop worrying about base performance unless you're on WordPress with a heavy theme. You probably already pass.
Decide which thin pages should be indexed and noindex the rest, rather than trying to bulk them up.

None of these are new. The takeaway from 8,000 audits isn't what to do — it's how few sites have done it.

If you want to see where your site sits in this distribution, run an audit — it takes about 12 seconds.

Audit Every Page on Your Site from sitemap.xml in One Command

Aaron VanSledright — Tue, 12 May 2026 14:00:42 +0000

"Audit my site" almost never means one URL. It means the homepage, the pricing page, the top twenty blog posts, every product, every category, every location page. On any real site that's hundreds to thousands of URLs, and clicking each one through a free checker is not a workflow — it's a way to lose an afternoon.

This post walks through the workflow we recommend instead: pull your sitemap.xml, hand the URL list to the batch audit endpoint, and export a single CSV ranked by priority. It's ~40 lines of Python. It works on any site that publishes a sitemap. And the size of your site tells you which plan tier to start on.

The whole script

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

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

# 1. Fetch the sitemap
xml = requests.get(SITEMAP_URL, timeout=20).text
ns = {"sm": "http://www.sitemaps.org/schemas/sitemap/0.9"}
root = ET.fromstring(xml)
urls = [loc.text for loc in root.findall(".//sm:url/sm:loc", ns)]

print(f"Found {len(urls)} URLs in sitemap")

# 2. Batch audit (chunked at 50 to stay under per-call limits)
rows = []
for i in range(0, len(urls), 50):
    chunk = urls[i:i + 50]
    r = requests.post(
        f"{BASE}/audit/batch",
        headers={"X-API-Key": API_KEY},
        json={"urls": chunk},
        timeout=180,
    )
    r.raise_for_status()
    for result in r.json()["results"]:
        rows.append({
            "url": result["url"],
            "score": result.get("score", 0),
            "grade": result.get("grade", "F"),
            "seo": result.get("categories", {}).get("seo", 0),
            "performance": result.get("categories", {}).get("performance", 0),
            "accessibility": result.get("categories", {}).get("accessibility", 0),
            "ai_readability": result.get("categories", {}).get("ai_readability", 0),
            "priority_issues": len(result.get("priority", [])),
        })

# 3. Sort worst-first and write CSV
rows.sort(key=lambda r: r["score"])
with open("audit-report.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(rows)

print(f"Wrote {len(rows)} rows to audit-report.csv")
print(f"Worst page: {rows[0]['url']} ({rows[0]['score']})")

That's the whole thing. Drop it in a audit.py, set SEOSCORE_API_KEY, run it, open the CSV in whatever spreadsheet you like.

Why batch matters

Running 500 URLs through GET /audit one at a time means 500 round trips, 500 rate-limit hits, and 500 chances for a transient error to break the loop. POST /audit/batch accepts up to 50 URLs per call, runs them concurrently on our side, and returns a single response. For 500 URLs you do 10 batch calls instead of 500 sequential ones, and the whole audit finishes in two or three minutes.

Batch is not available on the free tier — it's the line where a free SEO checker stops being useful and an API starts paying for itself.

The cheapest tier that lets you re-audit at the cadence you actually want is the right tier. If your sitemap has 3,000 URLs and you want a Monday-morning snapshot every week, that's 12,000 audits/month — Pro covers it with room to spare.

Handling sitemap indexes

Most large sites don't publish a flat sitemap.xml; they publish a sitemap index that points at child sitemaps. The script above breaks on those. Two extra lines fix it:

def collect_urls(sitemap_url):
    xml = requests.get(sitemap_url, timeout=20).text
    root = ET.fromstring(xml)
    # Sitemap index — recurse
    if root.tag.endswith("sitemapindex"):
        urls = []
        for child in root.findall(".//sm:sitemap/sm:loc", ns):
            urls.extend(collect_urls(child.text))
        return urls
    # Regular sitemap
    return [loc.text for loc in root.findall(".//sm:url/sm:loc", ns)]

urls = collect_urls(SITEMAP_URL)

That's enough to handle WordPress (Yoast/Rank Math both publish indexes), Shopify (one index per resource type), and most enterprise CMS setups.

Make the CSV actionable

Sorting by score gets you "worst pages first." That's a start, but the high-value moves are usually:

High-traffic pages with mid-tier scores. A blog post with 12,000 pageviews/month and a score of 72 is worth fixing before a product page with 40 pageviews and a score of 41.
Pages with a low category score even if overall is fine. A product page scoring 85 overall but 58 in accessibility is an ADA risk you don't want to ignore.
Pages that just regressed. That's where historical tracking comes in — see the historical SEO score tracking post for the /history endpoint that adds month-over-month deltas to each row.

To join your audit report to traffic data, export GA4 or Search Console to CSV and merge in pandas:

import pandas as pd
audit = pd.read_csv("audit-report.csv")
traffic = pd.read_csv("ga4-pages.csv")  # url, pageviews
joined = audit.merge(traffic, on="url", how="left").fillna(0)
joined["impact"] = (100 - joined["score"]) * joined["pageviews"]
joined.sort_values("impact", ascending=False).head(50).to_csv("priority.csv")

That gives you a 50-row priority list ranked by expected impact of a fix, not just by raw score. The pages that show up at the top are the ones that are bad and matter.

Scheduling it

Once the script works, the obvious next step is running it weekly. A cron line on any server:

0 8 * * 1 /usr/bin/python3 /home/you/audit.py >> /var/log/seoaudit.log 2>&1

Or as a GitHub Action that posts the diff to Slack:

name: Weekly SEO audit
on:
  schedule:
    - cron: "0 8 * * 1"
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: {python-version: "3.11"}
      - run: pip install requests
      - run: python audit.py
        env:
          SEOSCORE_API_KEY: ${{ secrets.SEOSCORE_API_KEY }}
      - uses: actions/upload-artifact@v4
        with:
          name: audit-report
          path: audit-report.csv

The agency-monitor-setup post has a more involved Slack-alerting variant if you want to skip the artifact and just get pinged when scores drop.

What you do not want to do

A few traps we see people fall into:

Auditing the homepage and assuming the rest follows. Templates differ. Product pages and blog posts on the same site routinely score 15+ points apart. If you haven't sampled the long tail, you haven't audited the site.
Hammering the API with 500 separate GET /audit calls instead of using batch. It's slower, it hits rate limits, and on Pro you'll eat through your monthly cap five times faster than you needed to.
Treating the CSV as a static deliverable. The first audit is a baseline. The value compounds when you run it weekly and watch the trend — which is exactly what the historical endpoints are for.

Getting started

Pull your sitemap URL, copy the script above, set SEOSCORE_API_KEY, and run it. If your sitemap has more than a few hundred URLs, grab a Basic key so you've got room to re-run the audit on a weekly cadence. The first run gives you a baseline; the fourth run is where the trend becomes useful.

If you've got an enterprise sitemap with 10,000+ URLs and want help architecting the right batch size and cadence, the Ultra tier ships with that headroom built in.

Build a Live Site Monitoring Dashboard in 100 Lines of Python

Aaron VanSledright — Thu, 07 May 2026 17:32:08 +0000

There's a class of internal tool that's perpetually under-built: the "look at this metric across our things" dashboard. Status of the deploy. Score of the SEO audit. Latency of the regional endpoints. We treat these like full-stack projects when they should be one Python file.

This post walks through a 95-line single-file Flask dashboard I built to monitor SEO scores across a list of URLs. The same architecture works for any periodic JSON endpoint — score cards with deltas and sparklines, auto-refresh in the browser, runs anywhere Flask runs.

You can use the live version right now without signing up for anything: https://seoscoreapi.com/demo/dashboard. And the entire source is one downloadable file: /downloads/dashboard.py.

What we're building

A page that:

Polls a list of URLs every N minutes through an external API
Renders one card per URL with score, grade, delta vs. previous poll, category breakdown, and a 30-day sparkline
Highlights cards green/yellow/red based on score movement
Auto-refreshes in the browser via meta tag (no JS framework)
Caches results in memory so the page renders instantly even when the API call is mid-flight

No build step. No webpack. No Redis. No celery. One Python file.

The data source

I'm using SEO Score API because it's what I work on, but the pattern is identical for any JSON API that returns a numeric score per URL plus a timeseries endpoint for history. If you're following along with a different API, swap the two SDK calls (audit() and history()) for whatever your data source provides.

Install:

pip install flask seoscoreapi

The architecture in three pieces

A shared state dict mapping URL → latest result, guarded by a lock.
A background polling thread that walks the URL list, calls the API, and writes into the state dict.
A Flask route that reads the state dict and renders an HTML template.

Every other piece — the sparkline math, the category breakdown, the auto-refresh — is template stuff. The architecture is just three things.

The state dict

state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()

That's the entire data model. The dict is keyed by URL; values are whatever the latest poll produced. Initial state is {"loading": True} for each URL, which the template can render as a loading state until the first real poll completes.

The lock is necessary because the background thread writes while the Flask route reads. Both happen on different threads.

The polling function

def refresh_one(url):
    """Run an audit + fetch history for one URL, store result in `state`."""
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}

Two API calls per URL. audit() returns the current score and category breakdown; history() returns the timeseries for the sparkline. The delta is computed by subtracting the previous score (held in the state dict from the last poll) from the new one.

The try/except is intentional. Exceptions during a poll shouldn't kill the thread — they should mark the card as error and let the next poll retry.

The polling loop

def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()

A daemon thread that walks the URL list serially and sleeps between cycles. Sequential, not concurrent, on purpose: it's polite to the API and the dashboard's job isn't to hammer.

For a small URL list (< 25 URLs polled every 15 min) one thread is plenty. If you need to monitor hundreds of URLs, swap the inner loop for concurrent.futures.ThreadPoolExecutor(max_workers=10). But check your API's rate limit first.

The Flask route

@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))

That's it. The route copies the state dict (cheap, ~hundreds of small dicts) under the lock and renders. The page never waits on the API — it always returns whatever the last poll produced. If a poll is in flight, the user sees yesterday's number with yesterday's timestamp; if it's fresh, they see the latest.

The status colors

def status_for(delta):
    if delta is None:
        return "neutral"
    if delta <= -5:
        return "critical"
    if delta < 0:
        return "warning"
    return "ok"

A single function decides the card color. -5 or worse is red, any negative is yellow, anything else is green. The thresholds are arbitrary; tune to your data.

The sparkline

The sparkline is an inline SVG <polyline> with points computed in the Jinja template:

<svg viewBox="0 0 100 30" preserveAspectRatio="none" width="100%">
  <polyline fill="none" stroke="#60a5fa" stroke-width="1.5"
    points="{% for s in data.spark %}{{ loop.index0 * (100 / (data.spark|length - 1)) }},{{ 30 - (s * 0.3) }} {% endfor %}" />
</svg>

Two things make this work:

viewBox="0 0 100 30" plus preserveAspectRatio="none" lets the SVG stretch to whatever width the card is, without distorting the line in any meaningful way.
The y-coordinate 30 - score * 0.3 works because scores are 0–100 and we want them on a 0–30 viewBox. For a different range, normalize the values first or change the multiplier.

That's the whole sparkline. No Chart.js, no D3, no canvas tricks. Inline SVG is underrated for this kind of single-purpose visualization.

The auto-refresh

<meta http-equiv="refresh" content="60">

Yes, a <meta refresh> tag. It works perfectly for this use case and requires zero JavaScript. The browser refreshes the page every 60 seconds; the route reads the latest state dict; you see fresh data.

If you need finer control (e.g., update without losing scroll position) you'd swap this for a small fetch() polling loop. For a hallway-TV dashboard, the meta refresh is fine.

The full file

About 95 lines including the template:

import os
import threading
import time
from datetime import datetime

from flask import Flask, render_template_string
from seoscoreapi import audit, history

API_KEY = os.environ["SEOSCORE_API_KEY"]
URLS = [u.strip() for u in os.environ["DASHBOARD_URLS"].split(",") if u.strip()]
POLL_INTERVAL = int(os.getenv("POLL_INTERVAL_SECONDS", "900"))

app = Flask(__name__)
state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()


def status_for(delta):
    if delta is None: return "neutral"
    if delta <= -5: return "critical"
    if delta < 0: return "warning"
    return "ok"


def refresh_one(url):
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}


def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()


TEMPLATE = """..."""  # see full source for the HTML


@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)

The HTML template is roughly 50 lines of Jinja + CSS — readable, no framework, no build step. Grab the full file here.

Running it

export SEOSCORE_API_KEY=sk_your_key_here
export DASHBOARD_URLS="https://yoursite.com,https://yoursite.com/pricing"
python dashboard.py

Open http://localhost:8080. The first poll runs immediately, so within a few seconds the cards populate.

Deploying it

Three lines of Dockerfile:

FROM python:3.12-slim
RUN pip install flask seoscoreapi
COPY dashboard.py /app/dashboard.py
ENV SEOSCORE_API_KEY="" DASHBOARD_URLS=""
CMD python /app/dashboard.py

Drop on Fly.io, Railway, a Pi, a $5 VPS, or a Kubernetes pod. Stateless — just provision env vars and go.

Where to extend it

Three extensions I get asked about, all in 5–10 lines on top of the baseline:

1. Webhook alerts on regression

Add to refresh_one:

if delta is not None and delta <= -5:
    requests.post(SLACK_WEBHOOK, json={
        "text": f":warning: {url} dropped {delta} points to {result['score']}"
    })

2. Per-URL alert thresholds

Replace URLS with a config dict:

URLS = {
    "https://yoursite.com": {"critical_drop": 3, "warning_drop": 1},
    "https://yourblog.com": {"critical_drop": 8, "warning_drop": 4},
}

Then status_for(delta, thresholds) checks the per-URL values.

3. Multi-team views

Add a ?team=growth query param. URLs gain a team field. The route filters:

team = request.args.get("team")
filtered = {u: d for u, d in state.items() if not team or d.get("team") == team}

Same dashboard instance serves every team's view.

What I'd do differently for production

If this dashboard graduated from "office hallway TV" to "monitoring our customer-facing thing", I'd change three things:

Persist state to SQLite. The current dict gets wiped on restart. SQLite adds maybe 10 lines and means the dashboard remembers history across deploys.
Switch sequential polling to a thread pool. For 100+ URLs, sequential is too slow.
Move the meta refresh to a fetch() loop. Avoids losing scroll position on long pages and lets us update without a full reload.

None of these are necessary for the v0. Premature complexity is its own problem.

The takeaway

You don't need a SaaS observability product to know when one of your metrics regresses. A Flask file, an external API, and 30 minutes is enough for most internal monitoring needs. The interesting bits — the polling pattern, the inline SVG sparkline, the meta refresh — are decades-old techniques that still work fine.

The full source: https://seoscoreapi.com/downloads/dashboard.py
The live demo: https://seoscoreapi.com/demo/dashboard

If you build something interesting on top of this, I'd love to see it.

Build a Live Site Monitoring Dashboard in 100 Lines of Python

Aaron VanSledright — Thu, 07 May 2026 17:32:08 +0000

You can use the live version right now without signing up for anything: https://seoscoreapi.com/demo/dashboard. And the entire source is one downloadable file: /downloads/dashboard.py.

What we're building

A page that:

Polls a list of URLs every N minutes through an external API
Renders one card per URL with score, grade, delta vs. previous poll, category breakdown, and a 30-day sparkline
Highlights cards green/yellow/red based on score movement
Auto-refreshes in the browser via meta tag (no JS framework)
Caches results in memory so the page renders instantly even when the API call is mid-flight

No build step. No webpack. No Redis. No celery. One Python file.

The data source

Install:

pip install flask seoscoreapi

The architecture in three pieces

A shared state dict mapping URL → latest result, guarded by a lock.
A background polling thread that walks the URL list, calls the API, and writes into the state dict.
A Flask route that reads the state dict and renders an HTML template.

Every other piece — the sparkline math, the category breakdown, the auto-refresh — is template stuff. The architecture is just three things.

The state dict

state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()

The lock is necessary because the background thread writes while the Flask route reads. Both happen on different threads.

The polling function

def refresh_one(url):
    """Run an audit + fetch history for one URL, store result in `state`."""
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}

The try/except is intentional. Exceptions during a poll shouldn't kill the thread — they should mark the card as error and let the next poll retry.

The polling loop

def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()

A daemon thread that walks the URL list serially and sleeps between cycles. Sequential, not concurrent, on purpose: it's polite to the API and the dashboard's job isn't to hammer.

The Flask route

@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))

The status colors

def status_for(delta):
    if delta is None:
        return "neutral"
    if delta <= -5:
        return "critical"
    if delta < 0:
        return "warning"
    return "ok"

A single function decides the card color. -5 or worse is red, any negative is yellow, anything else is green. The thresholds are arbitrary; tune to your data.

The sparkline

The sparkline is an inline SVG <polyline> with points computed in the Jinja template:

<svg viewBox="0 0 100 30" preserveAspectRatio="none" width="100%">
  <polyline fill="none" stroke="#60a5fa" stroke-width="1.5"
    points="{% for s in data.spark %}{{ loop.index0 * (100 / (data.spark|length - 1)) }},{{ 30 - (s * 0.3) }} {% endfor %}" />
</svg>

Two things make this work:

viewBox="0 0 100 30" plus preserveAspectRatio="none" lets the SVG stretch to whatever width the card is, without distorting the line in any meaningful way.
The y-coordinate 30 - score * 0.3 works because scores are 0–100 and we want them on a 0–30 viewBox. For a different range, normalize the values first or change the multiplier.

That's the whole sparkline. No Chart.js, no D3, no canvas tricks. Inline SVG is underrated for this kind of single-purpose visualization.

The auto-refresh

<meta http-equiv="refresh" content="60">

If you need finer control (e.g., update without losing scroll position) you'd swap this for a small fetch() polling loop. For a hallway-TV dashboard, the meta refresh is fine.

The full file

About 95 lines including the template:

import os
import threading
import time
from datetime import datetime

from flask import Flask, render_template_string
from seoscoreapi import audit, history

API_KEY = os.environ["SEOSCORE_API_KEY"]
URLS = [u.strip() for u in os.environ["DASHBOARD_URLS"].split(",") if u.strip()]
POLL_INTERVAL = int(os.getenv("POLL_INTERVAL_SECONDS", "900"))

app = Flask(__name__)
state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()


def status_for(delta):
    if delta is None: return "neutral"
    if delta <= -5: return "critical"
    if delta < 0: return "warning"
    return "ok"


def refresh_one(url):
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}


def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()


TEMPLATE = """..."""  # see full source for the HTML


@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)

The HTML template is roughly 50 lines of Jinja + CSS — readable, no framework, no build step. Grab the full file here.

Running it

export SEOSCORE_API_KEY=sk_your_key_here
export DASHBOARD_URLS="https://yoursite.com,https://yoursite.com/pricing"
python dashboard.py

Open http://localhost:8080. The first poll runs immediately, so within a few seconds the cards populate.

Deploying it

Three lines of Dockerfile:

FROM python:3.12-slim
RUN pip install flask seoscoreapi
COPY dashboard.py /app/dashboard.py
ENV SEOSCORE_API_KEY="" DASHBOARD_URLS=""
CMD python /app/dashboard.py

Drop on Fly.io, Railway, a Pi, a $5 VPS, or a Kubernetes pod. Stateless — just provision env vars and go.

Where to extend it

Three extensions I get asked about, all in 5–10 lines on top of the baseline:

1. Webhook alerts on regression

Add to refresh_one:

if delta is not None and delta <= -5:
    requests.post(SLACK_WEBHOOK, json={
        "text": f":warning: {url} dropped {delta} points to {result['score']}"
    })

2. Per-URL alert thresholds

Replace URLS with a config dict:

URLS = {
    "https://yoursite.com": {"critical_drop": 3, "warning_drop": 1},
    "https://yourblog.com": {"critical_drop": 8, "warning_drop": 4},
}

Then status_for(delta, thresholds) checks the per-URL values.

3. Multi-team views

Add a ?team=growth query param. URLs gain a team field. The route filters:

team = request.args.get("team")
filtered = {u: d for u, d in state.items() if not team or d.get("team") == team}

Same dashboard instance serves every team's view.

What I'd do differently for production

If this dashboard graduated from "office hallway TV" to "monitoring our customer-facing thing", I'd change three things:

Persist state to SQLite. The current dict gets wiped on restart. SQLite adds maybe 10 lines and means the dashboard remembers history across deploys.
Switch sequential polling to a thread pool. For 100+ URLs, sequential is too slow.
Move the meta refresh to a fetch() loop. Avoids losing scroll position on long pages and lets us update without a full reload.

None of these are necessary for the v0. Premature complexity is its own problem.

The takeaway

The full source: https://seoscoreapi.com/downloads/dashboard.py
The live demo: https://seoscoreapi.com/demo/dashboard

If you build something interesting on top of this, I'd love to see it.

I built a WordPress Plugin For Generating Images With Nano Banana

Aaron VanSledright — Thu, 19 Mar 2026 16:49:09 +0000

AI is every where. Accept it. Anyway, I had a random thought last night about having a WordPress plugin that allows you to generate images on the fly for your posts. Pictures increase engagement on posts so, what if we just inline Nano Banana directly into Gutenberg?

This morning I built this plugin which is a simple API call to Google’s Gemini AI Studio through a Gutenberg block.

Type your prompt
Choose your model
Hit generate
Insert Simple!

Once the image is inserted into the post it turns the block into a standard image block so its as easy to manage as any other image.

I submitted the plugin to the official WordPress repository but it takes a while to get approved. So, if you want to add it to your own WordPress instance feel free to message me and I’ll give you access to the repository!