SEO Audit API in Python: Audit a List of Sites, Export to CSV
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:
Authorization: Bearer YOUR_API_KEY
Keep the key out of the script itself. Export it as an environment variable and read it at startup:
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:
example.comexample.orgshop.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
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 CSVThe 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".
"""Audit a list of sites with the SEOReport API and export the findings to CSV."""import csvimport osimport sysimport timeimport requestsBASE = "https://seoreport.dev/api/v1/reports"IN_FLIGHT = 5 # reports running at the same timeSUBMIT_PAUSE = 2 # seconds between submissionsMAX_WAIT = 600 # seconds before a report that never finishes is recordedCSV_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")))continuebody = 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"], Nonereturn None, f"HTTP {resp.status_code} after {attempts} attempts"
The response codes it handles each mean something different for a batch:
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.
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 = []breakif error:done.append({"site": site, "job_id": "", "error": error})else:running[job_id] = (site, time.monotonic())time.sleep(SUBMIT_PAUSE)wait = 0for job_id, (site, started) in list(running.items()):envelope = get_status(job_id)state = envelope["report"]["status"]error = Noneif state in ("queued", "running"):if time.monotonic() - started < MAX_WAIT:wait = max(wait, envelope["pollAfterMs"] / 1000)continueerror = 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:
targetUrlis the address that was actually audited. If your input redirects to another host on the same domain, for example from the bare domain towww, the audit follows it, so keep both your input and this value.auditedAtis when the audit ran; the script writes it to theaudited_atcolumn.score.overallis the 0 to 100 score for that site on that day.view.sectionsis a list of report sections. The one whosekeyisfull_findingsholdsdetail.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.
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"]})continuetry: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"]})continuefor finding in findings:if finding["status"] not in ("fail", "warn"):continuewriter.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:
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.
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:
import csvfrom collections import Counterwith 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.
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.