API de auditoria de SEO em Python: audite uma lista de sites e exporte CSV
Um script Python pronto para a API de auditoria de SEO do SEOReport: envie uma lista de sites, consulte cada relatório até ficar pronto e exporte os achados para um CSV.
Para auditar uma lista de sites com Python, você precisa de três chamadas à REST API do SEOReport por site: criar um relatório, consultar o status dele até que não esteja mais na fila nem em execução e ler o resultado final. O script abaixo faz isso para uma lista de domínios em texto simples, mantém alguns relatórios rodando ao mesmo tempo, espera entre as consultas o intervalo que a API pede e gera uma linha de CSV para cada achado com falha ou aviso. Ele exige Python 3.8 ou superior, o pacote requests e uma chave de API de um plano pago.
Todos os endpoints e campos usados aqui estão listados na página para desenvolvedores e na referência da API, ou fazem parte do JSON que o endpoint de resultado retorna. Os nomes dos campos foram conferidos com esse payload em outubro de 2026.
O que você precisa antes da primeira requisição
O acesso à API é vinculado à conta. Você cria uma chave nas configurações da conta assim que tiver um plano, e a mesma chave serve para a REST API e para o servidor MCP. Toda requisição a envia como token bearer:
Authorization: Bearer YOUR_API_KEY
Não deixe a chave no próprio script. Exporte-a como variável de ambiente e leia-a na inicialização:
export SEOREPORT_API_KEY="your key from account settings"pip install requests
Dois fatos sobre créditos definem como você monta a lista. Cada site novo que você audita pela API consome um crédito do seu plano, exatamente como aconteceria no site. Rodar um site para o qual você já tem um relatório não consome outro. Antes de um lote grande, compare o número de sites novos da lista com o saldo do seu plano; o script para de enviar quando os créditos acabam e ainda exporta o que terminou, mas é melhor saber antes.
A entrada é um arquivo de texto com um site por linha:
example.comexample.orgshop.example.net
Envie cada site pelo endereço da página inicial. A API lê a URL que você envia: um domínio sem caminho ou uma página inicial recebe uma auditoria de site que cobre a página inicial, as páginas listadas no sitemap e as páginas para as quais os links internos apontam, enquanto uma URL com caminho audita apenas aquela página. Para um portfólio de sites, o que você quer são domínios sem caminho.
Como as chamadas se encaixam
Diagram source
sequenceDiagram
participant S as Script Python
participant A as API do SEOReport
S->>A: POST /api/v1/reports com a URL do site
A-->>S: report.jobId e report.status
loop Até o status não ser mais queued nem running
S->>A: GET /api/v1/reports/jobId
A-->>S: report.status e pollAfterMs
end
S->>A: GET /api/v1/reports/jobId/result
A-->>S: Pontuação e todos os achados
S->>S: Acrescentar ao CSV os achados com falha e avisoA chamada de envio responde rápido com um ID de job. A chamada de status diz em que ponto o relatório está: queued, running e depois completed ou failed. Cada resposta de status também traz pollAfterMs, o número de milissegundos que a API sugere esperar antes de perguntar de novo. Enquanto o relatório ainda está rodando, são alguns segundos, e o valor cai para 0 quando o relatório termina. A maioria dos relatórios fica pronta em menos de um minuto.
Passo 1: enviar cada site e tratar recusas
A função de envio manda a URL e retorna o ID do job. Ela também decide o que fazer quando a API diz não, porque um script em lote precisa distinguir “vá mais devagar” de “pare” e de “pule este”.
"""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"
Cada código de resposta que ela trata significa uma coisa diferente para um lote:
Diagram source
flowchart TD
A["POST /api/v1/reports"] --> B{"Status HTTP"}
B -->|201| C["Guardar report.jobId e começar a consultar"]
B -->|503| D["Esperar e enviar de novo, até 3 tentativas"]
B -->|402| E["Créditos esgotados ou sem plano: parar de enviar"]
B -->|"429, ou outro erro"| F["Registrar o erro deste site e seguir"]Um 402 significa que a conta não pode rodar outro site novo agora, então todos os envios seguintes falhariam do mesmo jeito. O script para de enviar, deixa terminar os relatórios que já estão rodando e marca o resto da lista como não auditado, com a mensagem da API, para que o CSV ainda contenha tudo o que foi concluído. Um 503 significa que o serviço não conseguiu aceitar o relatório naquele momento, então o script espera e envia o mesmo site de novo, respeitando o cabeçalho Retry-After quando a API o envia e esperando 30 segundos quando não envia; depois de 3 recusas, ele registra o site e segue em frente. Um 429 não é repetido. Quando vem de um limite de auditoria de página, o code diz qual é, PAGE_AUDIT_HOURLY_LIMIT ou PAGE_AUDIT_DAILY_LIMIT, e o cabeçalho Retry-After informa os segundos até esse limite ser liberado, o que pode levar quase uma hora ou quase um dia; por isso o script registra a mensagem e passa adiante em vez de esperar. Qualquer outra coisa, como um endereço que não é um site público válido, é específica daquele site: o script registra e segue em frente.
Passo 2: consultar com moderação e manter alguns relatórios em andamento
Enviar 50 sites de uma vez e depois consultar os 50 a cada segundo é o padrão a evitar. A função abaixo mantém no máximo IN_FLIGHT relatórios rodando, faz uma pausa entre os envios e, entre as rodadas de consulta, espera o intervalo que a API sugere.
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
Trate qualquer status diferente de queued e running como final, e só completed como sucesso. MAX_WAIT é um limite de segurança, não uma duração esperada: a maioria dos relatórios termina bem antes, e ele só impede que um relatório que nunca termina deixe o lote inteiro em aberto. Quando uma execução falha, a resposta de status traz um objeto error com um code, uma message e um indicador retryable. Códigos como DNS_FAILURE, CRAWLER_BLOCKED e TLS_ERROR descrevem o próprio site: o domínio não resolveu, uma regra contra bots recusou a requisição ou a conexão segura falhou. Repetir dá a mesma resposta, e essa resposta, por si só, merece chegar ao dono do site. Nossa receita de pipeline de CI usa o mesmo objeto error para distinguir um deploy quebrado de uma auditoria que não pôde rodar.
Passo 3: ler os achados e gravar o CSV
Quando um relatório está concluído, GET /api/v1/reports/{id}/result retorna o resultado completo. Dentro de report, quatro partes importam para uma exportação:
targetUrlé o endereço que foi de fato auditado. Se a sua entrada redireciona para outro host do mesmo domínio, por exemplo do domínio sem www parawww, a auditoria segue o redirecionamento, então guarde tanto a sua entrada quanto esse valor.auditedAtdiz quando a auditoria rodou; o script grava esse valor na colunaaudited_at.score.overallé a pontuação de 0 a 100 daquele site naquele dia.view.sectionsé uma lista de seções do relatório. A seção cujakeyéfull_findingscontémdetail.findings, um objeto por achado.
Cada achado traz um status (fail, warn, pass ou info), um areaLabel que nomeia a parte do site a que ele se refere, um title, uma explicação whyItMatters e, para achados com falha ou aviso, um fix. O texto vem no idioma do relatório. As evidências específicas do site, como as URLs afetadas, ficam no relatório completo e não nesses campos, e é por isso que a última seção deste artigo salva uma cópia ao lado do 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])
Rode o script com a lista de entrada e um caminho de saída:
python audit_sites.py sites.txt findings.csv
Os sites que deram errado continuam no arquivo. Um site que não pôde ser auditado recebe uma linha not_audited com o motivo em note, e um relatório concluído cujos achados não puderam ser lidos recebe uma linha unreadable. Filtre por esses dois valores antes de compartilhar o arquivo: um CSV que descartasse um site em silêncio faria esse site parecer livre de problemas.
Quantas linhas esperar
Espere linhas para quase todos os sites. Em 249 sites externos auditados pelo SEOReport entre 23 de agosto e 4 de outubro de 2026, o relatório mediano sinalizou 14 problemas distintos (achados com falha ou aviso); um quarto dos sites teve 17 ou mais, e nenhum teve zero.
Multiplicar essa mediana pelo tamanho da sua lista dá uma primeira estimativa razoável do tamanho do arquivo: uma lista de 40 sites perto da mediana chega a cerca de 560 linhas. É coisa demais para ler linha por linha, e é para isso que existem as colunas area e finding. Ordene por finding e os problemas que se repetem no portfólio aparecem juntos:
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}")
Quando um achado falha em 12 de 40 sites, procure primeiro uma causa comum: um tema, um plugin ou um template de hospedagem compartilhado pode transformar 12 problemas em 1 correção aplicada 12 vezes. A comparação vale porque todos os sites do arquivo foram verificados com o mesmo método, e a coluna audited_at mostra quando. Cobrir o mesmo terreno com sessões de chat de IA exige muitas conversas separadas, cada uma começando do zero; este cálculo para um site de 500 páginas faz a conta.
Guarde o relatório completo ao lado do CSV
O CSV é uma visão de trabalho. Para arquivo, ou para mandar ao dono do site o diagnóstico inteiro, baixe cada relatório no formato de que precisar: pdf, md, txt ou 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)
O PDF traz uma capa, o resumo executivo gerado por IA, o detalhamento por categoria e todos os achados. Nosso passo a passo sobre o que um relatório com pontuação contém explica como ler cada parte.
Para continuar acompanhando os mesmos sites depois da primeira exportação, cadastre-os no monitoramento semanal com PUT /api/v1/monitors, enviando {"url": ..., "alertEmail": ...} para cada um. O monitoramento está incluído nos planos pagos, não consome créditos de relatório e só envia e-mail para o endereço de alerta quando aparece um novo achado de severidade crítica ou alta, quando um achado crítico é resolvido ou quando a pontuação muda de faixa.
Perguntas frequentes
Rodar o script de novo consome créditos de novo?
Não para os sites que já têm relatório. Quando um site já tem um relatório, a API pode devolver esse relatório existente em vez de rodar uma auditoria nova, então confira a coluna audited_at antes de tratar um segundo CSV como uma medição nova. O monitoramento semanal sempre roda uma auditoria nova, o que o torna a ferramenta mais adequada para acompanhar mudanças ao longo do tempo.
Posso auditar páginas específicas em vez de sites inteiros?
Sim. Coloque URLs completas, com caminho, no arquivo de entrada, e cada uma será auditada como página única. As auditorias de página têm limites próprios por hora e por dia. Quando você atinge um deles, a API responde 429 e o script registra cada página restante como não auditada, com a mensagem da API, para que você rode essas páginas depois. Para uma visão do site inteiro, use só endereços de página inicial.
Por que a URL auditada é diferente da que está na minha lista?
Antes de auditar, a API segue um redirecionamento que fica no mesmo domínio, então example.com pode ser auditado como www.example.com. Um redirecionamento para outro domínio não é seguido em silêncio: a auditoria mantém o seu endereço e informa o redirecionamento como um achado. Use a coluna site para cruzar com os seus próprios registros e audited_url para ler os resultados.
Um agente de IA pode fazer isso no lugar do script?
Sim. A mesma chave de API conecta qualquer agente compatível com MCP ao servidor MCP, que oferece create_report, get_report_status e get_report; nosso guia de configuração para agentes explica a configuração. Um script é a melhor opção para uma lista fixa rodando em horários definidos, porque roda de forma idêntica toda vez e deixa um arquivo que você pode comparar. Um agente se encaixa quando alguém quer fazer perguntas de acompanhamento sobre os achados de um site.
O CSV mostra como o Google indexou cada site?
Não. O SEOReport audita, de fora, o que cada site servia no momento da auditoria, e não lê dados do Search Console. Use o Search Console para ver o que o Google decidiu sobre uma URL, e os achados para ver o que no site pode estar causando isso.
Obtenha o diagnóstico completo do seu site
Um relatório baseado em evidências e um plano de ação priorizado, em um plano com créditos mensais.