Back to articles

SEO-Audit-API mit Python: Eine Liste von Websites prüfen, Export als CSV

SEOReport Team·
apipythonautomationseo-auditcsv-export

Ein lauffähiges Python-Skript für die SEO-Audit-API von SEOReport: Websites einreichen, jeden Bericht bis zum Ende abfragen und alle Befunde als CSV exportieren.

Um eine Liste von Websites mit Python zu prüfen, brauchen Sie pro Website drei Aufrufe der SEOReport REST API: einen Bericht anlegen, seinen Status abfragen, bis er nicht mehr wartet oder läuft, und das fertige Ergebnis lesen. Das Skript unten erledigt das für eine einfache Textliste von Domains, lässt einige Berichte gleichzeitig laufen, wartet zwischen den Abfragen so lange, wie die API es vorgibt, und erzeugt pro fehlgeschlagenem oder warnendem Befund eine CSV-Zeile. Es benötigt Python 3.8 oder neuer, das Paket requests und einen API-Schlüssel aus einem kostenpflichtigen Tarif.

Jeder hier verwendete Endpunkt und jedes Feld steht entweder auf der Entwicklerseite und in der API-Referenz oder ist Teil des JSON, das der Ergebnis-Endpunkt zurückgibt. Die Feldnamen wurden im Oktober 2026 mit diesem Payload abgeglichen.

Was Sie vor der ersten Anfrage brauchen

Der API-Zugang ist an ein Konto gebunden. Sie erstellen einen Schlüssel in Ihren Kontoeinstellungen, sobald Sie einen Tarif haben, und derselbe Schlüssel funktioniert für REST und für den MCP-Server. Jede Anfrage sendet ihn als Bearer-Token:

http
Authorization: Bearer YOUR_API_KEY

Halten Sie den Schlüssel aus dem Skript selbst heraus. Exportieren Sie ihn als Umgebungsvariable und lesen Sie ihn beim Start ein:

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

Zwei Fakten zu Credits bestimmen, wie Sie die Liste aufbauen. Jede neue Website, die Sie über die API prüfen, verbraucht einen Credit Ihres Tarifs, genau wie auf der Website. Eine Website, für die Sie bereits einen Bericht haben, verbraucht keinen weiteren. Vergleichen Sie vor einem großen Durchlauf die Zahl der neuen Websites in der Liste mit dem, was Ihr Tarif noch hergibt; das Skript hört auf einzureichen, wenn die Credits aufgebraucht sind, und exportiert trotzdem, was fertig wurde, aber es ist besser, das vorher zu wissen.

Die Eingabe ist eine Textdatei mit einer Website pro Zeile:

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

Reichen Sie jede Website mit der Adresse ihrer Startseite ein. Die API liest die URL, die Sie senden: Eine reine Domain oder Startseite erhält ein Website-Audit, das die Startseite sowie Seiten abdeckt, die ihre Sitemap listet und auf die ihre internen Links verweisen; eine URL mit Pfad prüft dagegen nur diese einzelne Seite. Für ein Portfolio von Websites sind reine Domains das Richtige.

Wie die Aufrufe zusammenspielen

loop[Bis der Status weder queued noch running ist]POST /api/v1/reports mit der URL der Websitereport.jobId und report.statusGET /api/v1/reports/jobIdreport.status und pollAfterMsGET /api/v1/reports/jobId/resultScore und vollständige BefundeFehler- und Warnbefunde an die CSV anhängenPython-SkriptSEOReport APIPython-SkriptSEOReport API
Diagram source
sequenceDiagram
    participant S as Python-Skript
    participant A as SEOReport API
    S->>A: POST /api/v1/reports mit der URL der Website
    A-->>S: report.jobId und report.status
    loop Bis der Status weder queued noch running ist
        S->>A: GET /api/v1/reports/jobId
        A-->>S: report.status und pollAfterMs
    end
    S->>A: GET /api/v1/reports/jobId/result
    A-->>S: Score und vollständige Befunde
    S->>S: Fehler- und Warnbefunde an die CSV anhängen

Der Einreichungsaufruf antwortet schnell mit einer Job-ID. Der Statusaufruf sagt Ihnen, wo der Bericht steht: queued, running, dann completed oder failed. Jede Statusantwort enthält außerdem pollAfterMs, die Anzahl Millisekunden, die Sie laut API vor der nächsten Abfrage warten sollten. Solange ein Bericht läuft, sind das einige Sekunden, und der Wert fällt auf 0, wenn der Bericht fertig ist. Die meisten Berichte sind in weniger als einer Minute fertig.

Schritt 1: Jede Website einreichen und Ablehnungen behandeln

Die Einreichungsfunktion sendet die URL und gibt die Job-ID zurück. Sie entscheidet auch, was zu tun ist, wenn die API ablehnt, denn ein Batch-Skript muss „langsamer“ von „aufhören“ und „diese überspringen“ unterscheiden.

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"

Die Antwortcodes, die sie behandelt, bedeuten für einen Batch jeweils etwas anderes:

201503402429 oder anderer FehlerPOST /api/v1/reportsHTTP-Statusreport.jobId behalten undmit dem Abfragen beginnenWarten, dann erneutsenden, bis zu 3 VersucheCredits verbraucht oderkein Tarif: EinreichenbeendenFehler für diese Websitefesthalten undweitermachen
Diagram source
flowchart TD
    A["POST /api/v1/reports"] --> B{"HTTP-Status"}
    B -->|201| C["report.jobId behalten und mit dem Abfragen beginnen"]
    B -->|503| D["Warten, dann erneut senden, bis zu 3 Versuche"]
    B -->|402| E["Credits verbraucht oder kein Tarif: Einreichen beenden"]
    B -->|"429 oder anderer Fehler"| F["Fehler für diese Website festhalten und weitermachen"]

Ein 402 bedeutet, dass das Konto gerade keine weitere neue Website prüfen kann, sodass jede folgende Einreichung genauso scheitern würde. Das Skript hört auf einzureichen, lässt die bereits laufenden Berichte fertig werden und markiert den Rest der Liste mit der Meldung der API als nicht geprüft; die CSV enthält also weiterhin alles, was abgeschlossen wurde. Ein 503 bedeutet, dass der Dienst den Bericht in diesem Moment nicht annehmen konnte; das Skript wartet und sendet dieselbe Website erneut, wobei es den Header Retry-After beachtet, wenn die API ihn sendet, und sonst 30 Sekunden wartet; nach 3 Ablehnungen hält es die Website fest und macht weiter. Ein 429 wird nicht wiederholt. Stammt er von einem Limit für Seiten-Audits, nennt sein code das Limit, PAGE_AUDIT_HOURLY_LIMIT oder PAGE_AUDIT_DAILY_LIMIT, und sein Header Retry-After gibt die Sekunden an, bis es aufgehoben wird. Das kann fast eine Stunde oder fast ein Tag sein, deshalb hält das Skript die Meldung fest und geht weiter, statt zu warten. Alles andere, etwa eine Adresse, die keine gültige öffentliche Website ist, betrifft nur diese Website: Das Skript hält es fest und geht weiter.

Schritt 2: Rücksichtsvoll abfragen und einige Berichte parallel laufen lassen

50 Websites auf einmal einzureichen und dann alle 50 jede Sekunde abzufragen, ist das Muster, das Sie vermeiden sollten. Die Funktion unten lässt höchstens IN_FLIGHT Berichte gleichzeitig laufen, pausiert zwischen den Einreichungen und schläft zwischen den Abfragerunden so lange, wie die API vorschlägt.

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

Behandeln Sie jeden Status außer queued und running als endgültig und nur completed als Erfolg. MAX_WAIT ist eine Sicherheitsgrenze, keine erwartete Dauer: Die meisten Berichte sind lange davor fertig, und die Grenze verhindert nur, dass ein Bericht, der nie fertig wird, den ganzen Batch offen hält. Schlägt ein Lauf fehl, enthält die Statusantwort ein error-Objekt mit einem code, einer message und einem Flag retryable. Codes wie DNS_FAILURE, CRAWLER_BLOCKED und TLS_ERROR beschreiben die Website selbst: Die Domain ließ sich nicht auflösen, eine Bot-Regel hat die Anfrage abgewiesen, oder die sichere Verbindung ist gescheitert. Ein erneuter Versuch liefert dieselbe Antwort, und diese Antwort ist es selbst wert, dem Inhaber der Website vorgelegt zu werden. Unser Rezept für die CI-Pipeline nutzt dasselbe error-Objekt, um ein fehlerhaftes Deployment von einem Audit zu unterscheiden, das nicht laufen konnte.

Schritt 3: Die Befunde lesen und die CSV schreiben

Ist ein Bericht fertig, liefert GET /api/v1/reports/{id}/result das vollständige Ergebnis. Innerhalb von report sind für einen Export vier Teile wichtig:

  • targetUrl ist die Adresse, die tatsächlich geprüft wurde. Leitet Ihre Eingabe auf einen anderen Host derselben Domain weiter, etwa von der reinen Domain auf www, folgt das Audit dieser Weiterleitung; behalten Sie also sowohl Ihre Eingabe als auch diesen Wert.
  • auditedAt gibt an, wann das Audit lief; das Skript schreibt den Wert in die Spalte audited_at.
  • score.overall ist der Score von 0 bis 100 für diese Website an diesem Tag.
  • view.sections ist eine Liste von Berichtsabschnitten. Der Abschnitt mit dem key full_findings enthält detail.findings, ein Objekt pro Befund.

Jeder Befund enthält einen status (fail, warn, pass oder info), ein areaLabel, das den betroffenen Bereich der Website benennt, einen title, eine Erklärung whyItMatters und bei fehlgeschlagenen und warnenden Befunden einen fix. Der Text ist in der Sprache des Berichts verfasst. Die websitespezifischen Belege, etwa die betroffenen URLs, stehen im vollständigen Bericht und nicht in diesen Feldern; deshalb legt der letzte Abschnitt dieses Artikels eine Kopie neben der CSV ab.

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])

Führen Sie es mit der Eingabeliste und einem Ausgabepfad aus:

bash
python audit_sites.py sites.txt findings.csv

Websites, bei denen etwas schiefging, bleiben in der Datei. Eine Website, die nicht geprüft werden konnte, erhält eine Zeile not_audited mit dem Grund in note, und ein fertiger Bericht, dessen Befunde sich nicht lesen ließen, erhält eine Zeile unreadable. Filtern Sie nach diesen beiden Werten, bevor Sie die Datei weitergeben: Eine CSV, die eine Website stillschweigend weggelassen hat, sähe aus wie eine Website ohne Probleme.

Wie viele Zeilen Sie erwarten können

Rechnen Sie bei fast jeder Website mit Zeilen. Bei 249 externen Websites, die SEOReport zwischen dem 23. August und dem 4. Oktober 2026 geprüft hat, meldete der Median-Bericht 14 verschiedene Probleme (fehlgeschlagene Prüfungen oder Warnungen); ein Viertel der Websites hatte 17 oder mehr, und keine hatte null.

Gemeldete Probleme pro Website, 249 externe Websites, Aug.–Okt. 2026

Dieser Median mal die Länge Ihrer Liste ergibt eine brauchbare erste Schätzung der Dateigröße: Eine Liste von 40 Websites nahe dem Median kommt auf rund 560 Zeilen. Das sind zu viele, um sie Zeile für Zeile zu lesen, und genau dafür gibt es die Spalten area und finding. Sortieren Sie nach finding, und die Probleme, die sich im Portfolio wiederholen, stehen beieinander:

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}")

Scheitert ein Befund bei 12 von 40 Websites, suchen Sie zuerst nach einer gemeinsamen Ursache: Ein gemeinsames Theme, Plugin oder Hosting-Template kann aus 12 Problemen 1 Fix machen, der 12-mal angewendet wird. Der Vergleich trägt, weil jede Website in der Datei mit derselben Methode geprüft wurde, und die Spalte audited_at zeigt, wann. Dieselbe Abdeckung über KI-Chat-Sitzungen erfordert viele getrennte Gespräche, die jeweils von vorn beginnen; diese Aufstellung für eine 500-Seiten-Website rechnet die Zahl durch.

Den vollständigen Bericht neben der CSV aufbewahren

Die CSV ist eine Arbeitsansicht. Für Ihre Unterlagen oder um einem Website-Inhaber die ganze Diagnose zu schicken, laden Sie jeden Bericht im benötigten Format herunter: pdf, md, txt oder 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)

Das PDF enthält ein Deckblatt, die KI-Zusammenfassung für die Geschäftsführung, die Aufschlüsselung nach Kategorien und die vollständigen Befunde. Unser Leitfaden zu was ein SEO-Bericht mit Score enthält erklärt, wie Sie jeden Teil lesen.

Um dieselben Websites nach dem ersten Export weiter zu beobachten, registrieren Sie sie mit PUT /api/v1/monitors für das wöchentliche Monitoring und senden dabei für jede {"url": ..., "alertEmail": ...}. Das Monitoring ist in kostenpflichtigen Tarifen enthalten, verbraucht keine Berichts-Credits und sendet nur dann eine E-Mail an die Alarmadresse, wenn ein neuer Befund mit kritischem oder hohem Schweregrad auftaucht, ein kritischer Befund behoben ist oder der Score in einen anderen Bereich wechselt.

Häufige Fragen

Verbraucht ein erneuter Lauf des Skripts erneut Credits?

Nicht für Websites, für die Sie bereits einen Bericht haben. Hat eine Website schon einen Bericht, kann die API diesen vorhandenen Bericht zurückgeben, statt ein neues Audit zu starten; prüfen Sie also die Spalte audited_at, bevor Sie eine zweite CSV als neue Messung behandeln. Das wöchentliche Monitoring startet immer ein neues Audit und ist deshalb das bessere Werkzeug, um Veränderungen über die Zeit zu verfolgen.

Kann ich einzelne Seiten statt ganzer Websites prüfen?

Ja. Tragen Sie vollständige URLs mit Pfad in die Eingabedatei ein, und jede wird als einzelne Seite geprüft. Seiten-Audits haben eigene stündliche und tägliche Limits. Erreichen Sie eines, antwortet die API mit 429, und das Skript markiert jede verbleibende Seite mit der Meldung der API als nicht geprüft, sodass Sie diese Seiten später prüfen können. Für eine websiteweite Sicht bleiben Sie bei Startseitenadressen.

Warum unterscheidet sich die geprüfte URL von der in meiner Liste?

Vor dem Audit folgt die API einer Weiterleitung, die auf derselben Domain bleibt; example.com kann also als www.example.com geprüft werden. Einer Weiterleitung auf eine andere Domain folgt sie nicht stillschweigend: Das Audit behält Ihre Adresse und meldet die Weiterleitung als Befund. Verwenden Sie die Spalte site für den Abgleich mit Ihren eigenen Daten und audited_url zum Lesen der Ergebnisse.

Kann ein KI-Agent das statt eines Skripts erledigen?

Ja. Derselbe API-Schlüssel verbindet jeden MCP-fähigen Agenten mit dem MCP-Server, der create_report, get_report_status und get_report anbietet; unsere Anleitung zur Einrichtung für Agenten beschreibt die Konfiguration. Für eine feste Liste nach Zeitplan passt ein Skript besser, weil es jedes Mal identisch läuft und eine Datei hinterlässt, die Sie vergleichen können. Ein Agent passt, wenn jemand Rückfragen zu den Befunden einer einzelnen Website stellen möchte.

Zeigt die CSV, wie Google jede Website indexiert hat?

Nein. SEOReport prüft von außen, was jede Website zum Zeitpunkt des Audits ausgeliefert hat, und liest keine Search-Console-Daten. Nutzen Sie die Search Console, um zu sehen, was Google über eine URL entschieden hat, und die Befunde, um zu sehen, was auf der Website die Ursache sein könnte.

Erhalten Sie die vollständige Diagnose Ihrer Website

Ein belegter Bericht und ein priorisierter Aktionsplan – in einem Plan mit monatlichen Credits.