Back to articles

SEO Audit API in Python: Audit a List of Sites, Export to CSV

SEOReport Team·
apipythonautomationseo-auditcsv-export

A working Python script for the SEOReport SEO audit API: submit a list of sites, poll each report until it is ready, and export the findings to one CSV file.

To audit a list of sites from Python, you need three calls to the SEOReport REST API for each site: create a report, poll its status until it is no longer queued or running, and read the finished result. The script below does that for a plain text list of domains, keeps a few reports running at once, waits as long as the API asks between polls, and produces one CSV row per failing or warning finding. It needs Python 3.8 or later, the requests package and an API key from a paid plan.

Every endpoint and field used here is either listed on the developers page and the API reference, or is part of the JSON the result endpoint returns. Field names were checked against that payload in October 2026.

What you need before the first request

API access is account-linked. You create a key in your account settings once you have a plan, and the same key works for REST and for the MCP server. Every request sends it as a bearer token:

http
Authorization: Bearer YOUR_API_KEY

Keep the key out of the script itself. Export it as an environment variable and read it at startup:

bash
export SEOREPORT_API_KEY="your key from account settings"
pip install requests

Two facts about credits shape how you build the list. Each new site you audit through the API uses a credit from your plan, exactly as it would on the website. Running a site you already have a report for does not use another one. Before a large batch, compare the number of new sites in the list with what your plan has left; the script stops submitting when credits run out and still exports what finished, but it is better to know in advance.

The input is a text file with one site per line:

text
example.com
example.org
shop.example.net

Submit each site as its homepage address. The API reads the URL you send: a bare domain or homepage gets a site audit covering the homepage plus pages its sitemap lists and its internal links point to, while a URL with a path audits that single page on its own. For a portfolio of sites, bare domains are what you want.

How the calls fit together

loop[Until status is not queued or running]POST /api/v1/reports with the site URLreport.jobId and report.statusGET /api/v1/reports/jobIdreport.status and pollAfterMsGET /api/v1/reports/jobId/resultscore and full findingsAppend failing and warning findings to the CSVPython scriptSEOReport APIPython scriptSEOReport API
Diagram source
sequenceDiagram
    participant S as Python script
    participant A as SEOReport API
    S->>A: POST /api/v1/reports with the site URL
    A-->>S: report.jobId and report.status
    loop Until status is not queued or running
        S->>A: GET /api/v1/reports/jobId
        A-->>S: report.status and pollAfterMs
    end
    S->>A: GET /api/v1/reports/jobId/result
    A-->>S: score and full findings
    S->>S: Append failing and warning findings to the CSV

The submit call returns quickly with a job ID. The status call tells you where the report is: queued, running, then completed or failed. Each status response also carries pollAfterMs, the number of milliseconds the API suggests you wait before asking again. While a report is still running that is a few seconds, and it drops to 0 when the report is done. Most reports finish in under a minute.

Step 1: submit each site and handle refusals

The submit function sends the URL and returns the job ID. It also decides what to do when the API says no, because a batch script has to tell "slow down" apart from "stop" and "skip this one".

python
"""Audit a list of sites with the SEOReport API and export the findings to CSV."""
import csv
import os
import sys
import time
import requests
BASE = "https://seoreport.dev/api/v1/reports"
IN_FLIGHT = 5 # reports running at the same time
SUBMIT_PAUSE = 2 # seconds between submissions
MAX_WAIT = 600 # seconds before a report that never finishes is recorded
CSV_FIELDS = ["site", "audited_url", "audited_at", "score", "status", "area",
"finding", "why_it_matters", "fix", "note", "job_id"]
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["SEOREPORT_API_KEY"]
class OutOfCredits(Exception):
"""The account cannot run another new site, so stop submitting."""
def submit(site, attempts=3):
"""Create a report for one site. Returns (job_id, None) or (None, error)."""
for _ in range(attempts):
resp = session.post(BASE, json={"url": site}, timeout=60)
if resp.status_code == 503:
time.sleep(int(resp.headers.get("Retry-After", "30")))
continue
body = resp.json()
if resp.status_code == 402:
raise OutOfCredits(body["error"])
if not body.get("success"):
return None, f"HTTP {resp.status_code}: {body.get('error')}"
return body["report"]["jobId"], None
return None, f"HTTP {resp.status_code} after {attempts} attempts"

The response codes it handles each mean something different for a batch:

201503402429, or another errorPOST /api/v1/reportsHTTP statusKeep report.jobId and startpollingWait, then send again, up to3 triesCredits used or no plan:stop submittingRecord the error for this siteand continue
Diagram source
flowchart TD
    A["POST /api/v1/reports"] --> B{"HTTP status"}
    B -->|201| C["Keep report.jobId and start polling"]
    B -->|503| D["Wait, then send again, up to 3 tries"]
    B -->|402| E["Credits used or no plan: stop submitting"]
    B -->|"429, or another error"| F["Record the error for this site and continue"]

A 402 means the account cannot run another new site right now, so every following submission would fail the same way. The script stops submitting, lets the reports already running finish, and marks the rest of the list as not audited with the API's message, so the CSV still holds everything that completed. A 503 means the service could not take the report at that moment, so the script waits and sends the same site again, honouring the Retry-After header when the API sends one and waiting 30 seconds when it does not; after 3 refusals it records the site and continues. A 429 is not retried. When it comes from a page-audit limit, its code says which one, PAGE_AUDIT_HOURLY_LIMIT or PAGE_AUDIT_DAILY_LIMIT, and its Retry-After header gives the seconds until that limit lifts, which can be most of an hour or most of a day, so the script records the message and moves on instead of waiting. Anything else, such as an address that is not a valid public website, is specific to that site: the script records it and moves on.

Step 2: poll politely and keep a few reports in flight

Submitting 50 sites at once and then polling all 50 every second is the pattern to avoid. The function below keeps at most IN_FLIGHT reports running, pauses between submissions, and sleeps for the interval the API suggests between polling rounds.

python
def get_status(job_id):
resp = session.get(f"{BASE}/{job_id}", timeout=60)
resp.raise_for_status()
return resp.json()
def audit(sites):
"""Submit every site, keep IN_FLIGHT running, return one outcome per site."""
pending, running, done = list(sites), {}, []
while pending or running:
while pending and len(running) < IN_FLIGHT:
site = pending.pop(0)
try:
job_id, error = submit(site)
except OutOfCredits as exc:
done += [{"site": s, "job_id": "", "error": str(exc)} for s in [site] + pending]
pending = []
break
if error:
done.append({"site": site, "job_id": "", "error": error})
else:
running[job_id] = (site, time.monotonic())
time.sleep(SUBMIT_PAUSE)
wait = 0
for job_id, (site, started) in list(running.items()):
envelope = get_status(job_id)
state = envelope["report"]["status"]
error = None
if state in ("queued", "running"):
if time.monotonic() - started < MAX_WAIT:
wait = max(wait, envelope["pollAfterMs"] / 1000)
continue
error = f"still {state} after {MAX_WAIT} seconds"
elif state != "completed":
detail = envelope.get("error") or {}
error = f"{state}: {detail.get('code', '')} {detail.get('message', '')}".strip()
del running[job_id]
done.append({"site": site, "job_id": job_id, "error": error})
if running:
time.sleep(max(wait, 3))
return done

Treat every status other than queued and running as final, and only completed as a success. MAX_WAIT is a safety limit, not an expected duration: most reports finish well inside it, and it only stops one report that never finishes from holding the whole batch open. When a run fails, the status response carries an error object with a code, a message and a retryable flag. Codes such as DNS_FAILURE, CRAWLER_BLOCKED and TLS_ERROR describe the site itself: the domain did not resolve, a bot rule refused the request, or the secure connection failed. Retrying those gives the same answer, and that answer is itself worth putting in front of the site owner. Our CI pipeline recipe uses the same error object to tell a broken deploy from an audit that could not run.

Step 3: read the findings and write the CSV

When a report is complete, GET /api/v1/reports/{id}/result returns the full result. Inside report, four parts matter for an export:

  • targetUrl is the address that was actually audited. If your input redirects to another host on the same domain, for example from the bare domain to www, the audit follows it, so keep both your input and this value.
  • auditedAt is when the audit ran; the script writes it to the audited_at column.
  • score.overall is the 0 to 100 score for that site on that day.
  • view.sections is a list of report sections. The one whose key is full_findings holds detail.findings, one object per finding.

Each finding carries a status (fail, warn, pass or info), an areaLabel that names the part of the site it concerns, a title, a whyItMatters explanation and, for failing and warning findings, a fix. The text is in the language of the report. The site-specific evidence, such as the affected URLs, is in the full report rather than in these fields, which is why the last section of this article saves a copy beside the CSV.

python
def read_findings(job_id):
resp = session.get(f"{BASE}/{job_id}/result", timeout=60)
resp.raise_for_status()
report = resp.json()["report"]
section = next((s for s in report["view"]["sections"] if s["key"] == "full_findings"), None)
if section is None or section["detail"] is None:
state = section["state"] if section else "missing"
raise RuntimeError(f"findings section is {state}")
return report, section["detail"]["findings"]
def export(outcomes, path):
with open(path, "w", newline="", encoding="utf-8") as fh:
writer = csv.DictWriter(fh, fieldnames=CSV_FIELDS)
writer.writeheader()
for item in outcomes:
if item["error"]:
writer.writerow({"site": item["site"], "status": "not_audited",
"note": item["error"], "job_id": item["job_id"]})
continue
try:
report, findings = read_findings(item["job_id"])
except (RuntimeError, requests.HTTPError) as exc:
writer.writerow({"site": item["site"], "status": "unreadable",
"note": str(exc), "job_id": item["job_id"]})
continue
for finding in findings:
if finding["status"] not in ("fail", "warn"):
continue
writer.writerow({
"site": item["site"],
"audited_url": report["targetUrl"],
"audited_at": report["auditedAt"],
"score": report["score"]["overall"],
"status": finding["status"],
"area": finding["areaLabel"],
"finding": finding["title"],
"why_it_matters": finding["whyItMatters"],
"fix": finding["fix"],
"job_id": item["job_id"],
})
if __name__ == "__main__":
with open(sys.argv[1], encoding="utf-8") as fh:
sites = [line.strip() for line in fh if line.strip()]
export(audit(sites), sys.argv[2])

Run it with the input list and an output path:

bash
python audit_sites.py sites.txt findings.csv

Sites that went wrong stay in the file. A site that could not be audited gets one not_audited row with the reason in note, and a completed report whose findings could not be read gets one unreadable row. Filter on those two values before you share the file: a CSV that silently dropped a site would look like a site with no problems.

How many rows to expect

Expect rows for nearly every site. In 249 external websites SEOReport audited between August 23 and October 4, 2026, the median report flagged 14 distinct issues (failing or warning findings); a quarter of sites had 17 or more, and none had zero.

Issues flagged per site, 249 external sites, Aug–Oct 2026

Multiplying that median by the length of your list gives a reasonable first estimate of the file size: a list of 40 sites near the median comes to roughly 560 rows. That is too many to read line by line, which is why the area and finding columns exist. Sort by finding and the issues that repeat across the portfolio surface together:

python
import csv
from collections import Counter
with open("findings.csv", encoding="utf-8") as fh:
rows = [r for r in csv.DictReader(fh) if r["status"] == "fail"]
for title, count in Counter(r["finding"] for r in rows).most_common(10):
print(f"{count:>3} {title}")

When one finding fails on 12 of 40 sites, look first for a shared cause: a common theme, plugin or hosting template can turn 12 problems into 1 fix applied 12 times. The comparison holds because every site in the file was checked with the same method, and the audited_at column shows when. Covering the same ground through AI chat sessions takes many separate conversations, each starting over; this breakdown for a 500-page site works through the count.

Keep the full report beside the CSV

The CSV is a working view. For records, or to send a site owner the whole diagnosis, download each report in the format you need: pdf, md, txt or json.

python
def save_report(job_id, path, fmt="pdf"):
resp = session.get(f"{BASE}/{job_id}/download", params={"format": fmt}, timeout=120)
resp.raise_for_status()
with open(path, "wb") as fh:
fh.write(resp.content)

The PDF carries a cover page, the AI executive summary, the category breakdown and the full findings. Our walkthrough of what a scored report contains explains how to read each part.

To keep watching the same sites after the first export, register them for weekly monitoring with PUT /api/v1/monitors, sending {"url": ..., "alertEmail": ...} for each. Monitoring is included with paid plans, does not use report credits, and emails the alert address only when a new critical or high-severity finding appears, a critical finding is resolved, or the score moves to a different band.

Common questions

Does running the script again use credits again?

Not for sites you already have a report for. When a site already has a report, the API can return that existing report instead of running a new audit, so check the audited_at column before you treat a second CSV as a fresh measurement. Weekly monitoring always runs a new audit, which makes it the better tool for watching change over time.

Can I audit specific pages instead of whole sites?

Yes. Put full URLs with paths in the input file and each one is audited as a single page. Page audits have their own hourly and daily limits. When you reach one, the API answers 429 and the script records each remaining page as not audited with the API's message, so you can run those pages later. For a site-wide view, keep to homepage addresses.

Why does the audited URL differ from the one in my list?

Before auditing, the API follows a redirect that stays on the same domain, so example.com may be audited as www.example.com. A redirect to a different domain is not followed silently: the audit keeps your address and reports the redirect as a finding. Keep the site column for joining against your own records and audited_url for reading the results.

Can an AI agent run this instead of a script?

Yes. The same API key connects any MCP-capable agent to the MCP server, which offers create_report, get_report_status and get_report; our agent setup guide covers the configuration. A script is the better fit for a fixed list on a schedule, because it runs identically every time and leaves a file you can compare. An agent fits when someone wants to ask follow-up questions about one site's findings.

Does the CSV show how Google indexed each site?

No. SEOReport audits what each site served at the time of the audit, from the outside, and does not read Search Console data. Use Search Console to see what Google decided about a URL, and the findings to see what on the site may be causing it.

Get the complete diagnosis of your site

An evidence-backed report and a prioritized action plan, on a plan with monthly credits.