Back to articles

API de auditoría SEO en Python: audite una lista de sitios y exporte a CSV

SEOReport Team·
apipythonautomationseo-auditcsv-export

Script de Python funcional para la API de auditoría SEO de SEOReport: envíe una lista de sitios, consulte cada informe hasta que esté listo y exporte los hallazgos a CSV.

Para auditar una lista de sitios desde Python, necesita tres llamadas a la API REST de SEOReport por cada sitio: crear un informe, consultar su estado hasta que deje de estar en cola o en ejecución, y leer el resultado final. El script de este artículo lo hace para una lista de dominios en texto plano, mantiene varios informes en ejecución a la vez, espera entre consultas el tiempo que pide la API y genera una fila de CSV por cada hallazgo con error o con advertencia. Requiere Python 3.8 o posterior, el paquete requests y una clave de API de un plan de pago.

Todos los endpoints y campos que se usan aquí figuran en la página para desarrolladores y en la referencia de la API, o forman parte del JSON que devuelve el endpoint de resultados. Los nombres de los campos se cotejaron con esa respuesta en octubre de 2026.

Lo que necesita antes de la primera petición

El acceso a la API está vinculado a la cuenta. La clave se crea en los ajustes de la cuenta una vez que tiene un plan, y la misma clave sirve para REST y para el servidor MCP. Cada petición la envía como token bearer:

http
Authorization: Bearer YOUR_API_KEY

No incluya la clave en el propio script. Expórtela como variable de entorno y léala al arrancar:

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

Dos datos sobre los créditos condicionan cómo se prepara la lista. Cada sitio nuevo que audite a través de la API consume un crédito de su plan, exactamente igual que en el sitio web. Ejecutar un sitio del que ya tiene un informe no consume otro. Antes de un lote grande, compare el número de sitios nuevos de la lista con lo que le queda en el plan; el script deja de enviar cuando se agotan los créditos y aun así exporta lo que ha terminado, pero es mejor saberlo de antemano.

La entrada es un archivo de texto con un sitio por línea:

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

Envíe cada sitio con la dirección de su página de inicio. La API lee la URL que usted envía: un dominio sin ruta o una página de inicio recibe una auditoría del sitio que abarca la página de inicio más las páginas que incluye su sitemap y a las que apuntan sus enlaces internos, mientras que una URL con ruta audita solo esa página. Para una cartera de sitios, lo que necesita son dominios sin ruta.

Cómo encajan las llamadas

loop[Hasta que el estado no sea queued ni running]POST /api/v1/reports con la URL del sitioreport.jobId y report.statusGET /api/v1/reports/jobIdreport.status y pollAfterMsGET /api/v1/reports/jobId/resultPuntuación y hallazgos completosAñade al CSV los hallazgos con error y con advertenciaScript de PythonAPI de SEOReportScript de PythonAPI de SEOReport
Diagram source
sequenceDiagram
    participant S as Script de Python
    participant A as API de SEOReport
    S->>A: POST /api/v1/reports con la URL del sitio
    A-->>S: report.jobId y report.status
    loop Hasta que el estado no sea queued ni running
        S->>A: GET /api/v1/reports/jobId
        A-->>S: report.status y pollAfterMs
    end
    S->>A: GET /api/v1/reports/jobId/result
    A-->>S: Puntuación y hallazgos completos
    S->>S: Añade al CSV los hallazgos con error y con advertencia

La llamada de envío responde enseguida con un ID de trabajo. La llamada de estado indica en qué punto está el informe: queued, running y, después, completed o failed. Cada respuesta de estado incluye además pollAfterMs, el número de milisegundos que la API sugiere esperar antes de volver a preguntar. Mientras el informe se está ejecutando son unos segundos, y baja a 0 cuando el informe ha terminado. La mayoría de los informes terminan en menos de un minuto.

Paso 1: envíe cada sitio y gestione los rechazos

La función de envío manda la URL y devuelve el ID de trabajo. También decide qué hacer cuando la API dice que no, porque un script por lotes tiene que distinguir entre "vaya más despacio", "pare" y "sáltese este".

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"

Cada código de respuesta que gestiona significa algo distinto para un lote:

201503402429 u otro errorPOST /api/v1/reportsCódigo HTTPGuarde report.jobId yempiece a consultarEspere y vuelva a enviar,hasta 3 intentosCréditos agotados o sinplan: deje de enviarRegistre el error de estesitio y continúe
Diagram source
flowchart TD
    A["POST /api/v1/reports"] --> B{"Código HTTP"}
    B -->|"201"| C["Guarde report.jobId y empiece a consultar"]
    B -->|503| D["Espere y vuelva a enviar, hasta 3 intentos"]
    B -->|"402"| E["Créditos agotados o sin plan: deje de enviar"]
    B -->|"429 u otro error"| F["Registre el error de este sitio y continúe"]

Un 402 significa que la cuenta no puede ejecutar otro sitio nuevo en ese momento, así que todos los envíos siguientes fallarían igual. El script deja de enviar, deja terminar los informes que ya están en marcha y marca el resto de la lista como no auditado con el mensaje de la API, de modo que el CSV sigue conteniendo todo lo que se completó. Un 503 significa que el servicio no pudo aceptar el informe en ese momento, así que el script espera y vuelve a enviar el mismo sitio, respetando la cabecera Retry-After cuando la API la envía y esperando 30 segundos cuando no; tras 3 rechazos, registra el sitio y continúa. Un 429 no se reintenta. Cuando proviene de un límite de auditorías de páginas, su code indica cuál, PAGE_AUDIT_HOURLY_LIMIT o PAGE_AUDIT_DAILY_LIMIT, y su cabecera Retry-After da los segundos que faltan para que ese límite se levante, que pueden ser casi una hora o casi un día, así que el script registra el mensaje y sigue en lugar de esperar. Cualquier otra cosa, como una dirección que no corresponde a un sitio web público válido, es propia de ese sitio: el script la registra y sigue.

Paso 2: consulte con moderación y mantenga varios informes en curso

Enviar 50 sitios de golpe y luego consultar los 50 cada segundo es justo el patrón que hay que evitar. La siguiente función mantiene como máximo IN_FLIGHT informes en ejecución, hace una pausa entre envíos y, entre rondas de consulta, espera el intervalo que sugiere la API.

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

Trate como final cualquier estado distinto de queued y running, y solo completed como éxito. MAX_WAIT es un límite de seguridad, no una duración esperada: la mayoría de los informes terminan con mucho margen, y solo sirve para que un informe que nunca termina no mantenga abierto todo el lote. Cuando una ejecución falla, la respuesta de estado incluye un objeto error con un code, un message y un indicador retryable. Códigos como DNS_FAILURE, CRAWLER_BLOCKED y TLS_ERROR describen el propio sitio: el dominio no se resolvió, una regla contra bots rechazó la petición o falló la conexión segura. Reintentarlos da la misma respuesta, y esa respuesta ya merece llegar al propietario del sitio. Nuestra receta para pipelines de CI usa el mismo objeto error para distinguir un despliegue roto de una auditoría que no se pudo ejecutar.

Paso 3: lea los hallazgos y escriba el CSV

Cuando un informe está completo, GET /api/v1/reports/{id}/result devuelve el resultado completo. Dentro de report, cuatro partes importan para la exportación:

  • targetUrl es la dirección que realmente se auditó. Si su entrada redirige a otro host del mismo dominio, por ejemplo del dominio sin www a www, la auditoría sigue la redirección, así que conserve tanto su entrada como este valor.
  • auditedAt indica cuándo se ejecutó la auditoría; el script lo escribe en la columna audited_at.
  • score.overall es la puntuación de 0 a 100 de ese sitio en ese día.
  • view.sections es una lista de secciones del informe. La que tiene key igual a full_findings contiene detail.findings, un objeto por hallazgo.

Cada hallazgo incluye un status (fail, warn, pass o info), un areaLabel que nombra la parte del sitio a la que se refiere, un title, una explicación whyItMatters y, para los hallazgos con error o con advertencia, un fix. El texto está en el idioma del informe. La evidencia concreta del sitio, como las URL afectadas, está en el informe completo y no en estos campos; por eso la última sección de este artículo guarda una copia junto al 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])

Ejecútelo con la lista de entrada y una ruta de salida:

bash
python audit_sites.py sites.txt findings.csv

Los sitios que han dado problemas siguen en el archivo. Un sitio que no se pudo auditar recibe una fila not_audited con el motivo en note, y un informe completado cuyos hallazgos no se pudieron leer recibe una fila unreadable. Filtre por esos dos valores antes de compartir el archivo: un CSV que hubiera eliminado un sitio sin avisar lo haría parecer un sitio sin problemas.

Cuántas filas cabe esperar

Cuente con filas para casi todos los sitios. En 249 sitios web externos que SEOReport auditó entre el 23 de agosto y el 4 de octubre de 2026, el informe mediano señalaba 14 problemas distintos (hallazgos con error o con advertencia); una cuarta parte de los sitios tenía 17 o más, y ninguno tenía cero.

Problemas señalados por sitio, 249 sitios externos, ago.–oct. de 2026

Multiplicar esa mediana por la longitud de su lista da una primera estimación razonable del tamaño del archivo: una lista de 40 sitios cercanos a la mediana ronda las 560 filas. Son demasiadas para leerlas una a una, y para eso existen las columnas area y finding. Ordene por finding y los problemas que se repiten en toda la cartera aparecerán juntos:

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

Cuando un hallazgo falla en 12 de 40 sitios, busque primero una causa común: un tema, un plugin o una plantilla de hosting compartidos pueden convertir 12 problemas en 1 corrección aplicada 12 veces. La comparación es válida porque todos los sitios del archivo se revisaron con el mismo método, y la columna audited_at indica cuándo. Cubrir lo mismo con sesiones de chat con IA exige muchas conversaciones independientes que empiezan de cero cada vez; este desglose para un sitio de 500 páginas hace las cuentas.

Guarde el informe completo junto al CSV

El CSV es una vista de trabajo. Para sus registros, o para enviar a un propietario el diagnóstico completo, descargue cada informe en el formato que necesite: pdf, md, txt o 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)

El PDF incluye una portada, el resumen ejecutivo generado con IA, el desglose por categorías y todos los hallazgos. Nuestro recorrido por qué contiene un informe con puntuación explica cómo leer cada parte.

Para seguir vigilando los mismos sitios después de la primera exportación, regístrelos para el seguimiento semanal con PUT /api/v1/monitors, enviando {"url": ..., "alertEmail": ...} para cada uno. El seguimiento está incluido en los planes de pago, no consume créditos de informe y solo envía un correo a la dirección de alerta cuando aparece un hallazgo nuevo de gravedad crítica o alta, se resuelve un hallazgo crítico o la puntuación pasa a otra franja.

Preguntas frecuentes

¿Volver a ejecutar el script consume créditos otra vez?

No para los sitios de los que ya tiene un informe. Cuando un sitio ya tiene un informe, la API puede devolver ese informe existente en lugar de ejecutar una auditoría nueva, así que revise la columna audited_at antes de tratar un segundo CSV como una medición nueva. El seguimiento semanal siempre ejecuta una auditoría nueva, por lo que es la mejor herramienta para observar los cambios a lo largo del tiempo.

¿Puedo auditar páginas concretas en lugar de sitios completos?

Sí. Ponga URL completas con ruta en el archivo de entrada y cada una se auditará como una sola página. Las auditorías de páginas tienen sus propios límites por hora y por día. Cuando alcance uno, la API responderá 429 y el script registrará cada página restante como no auditada con el mensaje de la API, para que pueda ejecutarlas más tarde. Para una visión de todo el sitio, limítese a las direcciones de las páginas de inicio.

¿Por qué la URL auditada es distinta de la de mi lista?

Antes de auditar, la API sigue una redirección que se mantenga en el mismo dominio, así que example.com puede auditarse como www.example.com. Una redirección a otro dominio no se sigue sin avisar: la auditoría conserva su dirección y notifica la redirección como hallazgo. Use la columna site para cruzar los datos con sus propios registros y audited_url para leer los resultados.

¿Puede un agente de IA hacer esto en lugar de un script?

Sí. La misma clave de API conecta cualquier agente compatible con MCP al servidor MCP, que ofrece create_report, get_report_status y get_report; nuestra guía de configuración para agentes explica cómo configurarlo. Un script encaja mejor con una lista fija que se ejecuta de forma programada, porque funciona exactamente igual cada vez y deja un archivo que se puede comparar. Un agente encaja cuando alguien quiere hacer preguntas de seguimiento sobre los hallazgos de un sitio.

¿Muestra el CSV cómo indexó Google cada sitio?

No. SEOReport audita desde fuera lo que cada sitio servía en el momento de la auditoría y no lee datos de Search Console. Use Search Console para ver qué decidió Google sobre una URL, y los hallazgos para ver qué elemento del sitio puede estar causándolo.

Obtenga el diagnóstico completo de su sitio

Un informe basado en evidencia y un plan de acción priorizado, con un plan de créditos mensuales.