Back to articles

Python SEO 감사 API: 사이트 목록 감사와 CSV 내보내기

SEOReport Team·
apipythonautomationseo-auditcsv-export

SEOReport SEO 감사 API용 Python 스크립트로 사이트 목록을 제출하고, 보고서가 준비될 때까지 폴링한 뒤 발견 사항을 CSV 하나로 내보냅니다.

Python으로 사이트 목록을 감사하려면 사이트마다 SEOReport REST API를 세 번 호출하면 됩니다. 보고서를 생성하고, 상태가 대기 중이나 실행 중이 아니게 될 때까지 폴링하고, 완료된 결과를 읽는 것입니다. 아래 스크립트는 도메인을 나열한 일반 텍스트 파일을 받아 이 작업을 수행하고, 보고서 몇 개를 동시에 실행하며, 폴링 사이에는 API가 요청하는 만큼 기다리고, 실패 또는 경고 발견 사항마다 CSV 행을 하나씩 만듭니다. Python 3.8 이상, requests 패키지, 유료 플랜의 API 키가 필요합니다.

여기에서 사용하는 모든 엔드포인트와 필드는 개발자 페이지와 API 레퍼런스에 나와 있거나, 결과 엔드포인트가 반환하는 JSON에 포함된 것입니다. 필드 이름은 2026년 10월에 해당 페이로드와 대조해 확인했습니다.

첫 요청 전에 준비할 것

API 접근은 계정에 연결됩니다. 플랜을 이용 중이라면 계정 설정에서 키를 만들 수 있으며, 같은 키를 REST와 MCP 서버 모두에 사용합니다. 모든 요청은 이 키를 베어러 토큰으로 보냅니다.

http
Authorization: Bearer YOUR_API_KEY

키를 스크립트 안에 직접 적지 마십시오. 환경 변수로 내보내고 시작할 때 읽어 들이십시오.

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

크레딧에 관한 두 가지 사실이 목록을 구성하는 방식에 영향을 줍니다. API로 감사하는 새 사이트마다 웹사이트에서와 똑같이 플랜의 크레딧이 하나씩 사용됩니다. 이미 보고서가 있는 사이트를 다시 실행할 때는 크레딧이 추가로 사용되지 않습니다. 대량 배치를 돌리기 전에 목록에 있는 새 사이트 수와 플랜에 남은 크레딧을 비교하십시오. 크레딧이 바닥나면 스크립트는 제출을 멈추고 완료된 결과는 그대로 내보내지만, 미리 알고 있는 편이 낫습니다.

입력 파일은 한 줄에 사이트 하나씩 적은 텍스트 파일입니다.

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

각 사이트는 홈페이지 주소로 제출하십시오. API는 보낸 URL을 그대로 읽습니다. 도메인만 보내거나 홈페이지를 보내면 홈페이지와 함께 사이트맵에 나열된 페이지, 내부 링크가 가리키는 페이지까지 다루는 사이트 감사가 실행되고, 경로가 포함된 URL을 보내면 그 페이지 하나만 감사합니다. 여러 사이트를 한꺼번에 관리한다면 도메인만 보내는 것이 맞습니다.

호출이 서로 이어지는 방식

loop[status가 queued나 running이 아닐 때까지]사이트 URL로 POST /api/v1/reportsreport.jobId와 report.statusGET /api/v1/reports/jobIdreport.status와 pollAfterMsGET /api/v1/reports/jobId/result점수와 전체 발견 사항실패 및 경고 발견 사항을 CSV에 추가Python 스크립트SEOReport APIPython 스크립트SEOReport API
Diagram source
sequenceDiagram
    participant S as Python 스크립트
    participant A as SEOReport API
    S->>A: 사이트 URL로 POST /api/v1/reports
    A-->>S: report.jobId와 report.status
    loop status가 queued나 running이 아닐 때까지
        S->>A: GET /api/v1/reports/jobId
        A-->>S: report.status와 pollAfterMs
    end
    S->>A: GET /api/v1/reports/jobId/result
    A-->>S: 점수와 전체 발견 사항
    S->>S: 실패 및 경고 발견 사항을 CSV에 추가

제출 호출은 작업 ID와 함께 바로 응답합니다. 상태 호출은 보고서가 어느 단계에 있는지 알려 줍니다. queued, running을 거쳐 completed 또는 failed가 됩니다. 각 상태 응답에는 pollAfterMs도 들어 있는데, 다시 요청하기 전에 기다리라고 API가 제안하는 밀리초 수입니다. 보고서가 실행 중일 때는 몇 초이고, 보고서가 끝나면 0이 됩니다. 대부분의 보고서는 1분 안에 끝납니다.

1단계: 사이트를 제출하고 거부 응답을 처리하기

제출 함수는 URL을 보내고 작업 ID를 반환합니다. API가 요청을 거부했을 때 어떻게 할지도 이 함수가 정합니다. 배치 스크립트는 "속도를 늦추라", "중단하라", "이 사이트는 건너뛰라"를 구분해야 하기 때문입니다.

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"

함수가 처리하는 응답 코드는 배치 작업에서 각각 다른 의미를 가집니다.

201503402429 또는 그 밖의 오류POST /api/v1/reportsHTTP 상태report.jobId를 보관하고폴링 시작기다린 뒤 다시 전송, 최대3회크레딧 소진 또는 플랜 없음:제출 중단이 사이트의 오류를기록하고 계속
Diagram source
flowchart TD
    A["POST /api/v1/reports"] --> B{"HTTP 상태"}
    B -->|"201"| C["report.jobId를 보관하고 폴링 시작"]
    B -->|503| D["기다린 뒤 다시 전송, 최대 3회"]
    B -->|"402"| E["크레딧 소진 또는 플랜 없음: 제출 중단"]
    B -->|"429 또는 그 밖의 오류"| F["이 사이트의 오류를 기록하고 계속"]

402는 지금 이 계정으로 새 사이트를 더 실행할 수 없다는 뜻이므로, 이후의 모든 제출도 같은 이유로 실패합니다. 스크립트는 제출을 멈추고, 이미 실행 중인 보고서는 끝까지 기다린 뒤, 목록의 나머지 사이트를 API 메시지와 함께 감사되지 않음으로 표시합니다. 그래서 CSV에는 완료된 결과가 모두 남습니다. 503은 서비스가 그 순간 보고서를 받을 수 없었다는 뜻이므로, 스크립트는 기다렸다가 같은 사이트를 다시 보냅니다. API가 Retry-After 헤더를 보내면 그 값을 따르고, 보내지 않으면 30초를 기다립니다. 3번 거부되면 그 사이트를 기록하고 다음으로 넘어갑니다. 429는 재시도하지 않습니다. 페이지 감사 한도 때문에 반환된 429라면 code가 어느 한도인지(PAGE_AUDIT_HOURLY_LIMIT 또는 PAGE_AUDIT_DAILY_LIMIT) 알려 주고, Retry-After 헤더가 한도가 풀릴 때까지 남은 초를 알려 줍니다. 이 시간은 거의 한 시간이 될 수도, 거의 하루가 될 수도 있으므로 스크립트는 기다리지 않고 메시지를 기록한 뒤 넘어갑니다. 유효한 공개 웹사이트가 아닌 주소 같은 그 밖의 오류는 해당 사이트에만 해당하므로, 역시 기록하고 넘어갑니다.

2단계: 예의 있게 폴링하고 보고서 몇 개를 동시에 실행하기

사이트 50개를 한꺼번에 제출하고 50개 모두를 매초 폴링하는 것은 피해야 할 방식입니다. 아래 함수는 동시에 실행되는 보고서를 최대 IN_FLIGHT개로 유지하고, 제출 사이에 잠시 쉬며, 폴링 라운드 사이에는 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

queued와 running을 제외한 모든 상태는 최종 상태로 보고, 그중 completed만 성공으로 취급하십시오. MAX_WAIT는 예상 소요 시간이 아니라 안전장치입니다. 대부분의 보고서는 이 시간보다 훨씬 빨리 끝나며, 이 값은 끝나지 않는 보고서 하나가 배치 전체를 붙잡아 두지 않도록 막을 뿐입니다. 실행이 실패하면 상태 응답에 code, message, retryable 플래그를 담은 error 객체가 포함됩니다. DNS_FAILURE, CRAWLER_BLOCKED, TLS_ERROR 같은 코드는 사이트 자체의 상태를 나타냅니다. 도메인이 조회되지 않았거나, 봇 차단 규칙이 요청을 거부했거나, 보안 연결이 실패했다는 뜻입니다. 이런 경우는 재시도해도 같은 결과가 나오며, 그 결과 자체가 사이트 소유자에게 전할 가치가 있는 정보입니다. CI 파이프라인 레시피에서도 같은 error 객체로 깨진 배포와 실행되지 못한 감사를 구분합니다.

3단계: 발견 사항을 읽고 CSV 작성하기

보고서가 완료되면 GET /api/v1/reports/{id}/result가 전체 결과를 반환합니다. report 안에서 내보내기에 중요한 부분은 네 가지입니다.

  • targetUrl은 실제로 감사한 주소입니다. 입력한 주소가 같은 도메인의 다른 호스트로 리디렉션된다면(예: 도메인만 있는 주소에서 www로) 감사는 그 리디렉션을 따라가므로, 입력값과 이 값을 모두 보관하십시오.
  • auditedAt은 감사가 언제 실행되었는지 알려 주며, 스크립트는 이 값을 audited_at 열에 기록합니다.
  • score.overall은 해당 날짜 해당 사이트의 0~100점 점수입니다.
  • view.sections는 보고서 섹션 목록입니다. key가 full_findings인 섹션의 detail.findings에 발견 사항이 하나당 객체 하나씩 들어 있습니다.

각 발견 사항에는 status(fail, warn, pass, info), 사이트의 어느 영역에 관한 것인지 나타내는 areaLabel, title, whyItMatters 설명, 그리고 실패 및 경고 발견 사항의 경우 fix가 들어 있습니다. 텍스트는 보고서 언어로 작성됩니다. 영향받는 URL 같은 사이트별 증거는 이 필드가 아니라 전체 보고서에 있습니다. 이 글의 마지막 섹션에서 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])

입력 목록과 출력 경로를 지정해 실행합니다.

bash
python audit_sites.py sites.txt findings.csv

문제가 생긴 사이트도 파일에 남습니다. 감사할 수 없었던 사이트는 note에 이유가 적힌 not_audited 행 하나를 갖고, 완료되었지만 발견 사항을 읽을 수 없었던 보고서는 unreadable 행 하나를 갖습니다. 파일을 공유하기 전에 이 두 값으로 필터링해 보십시오. 사이트 하나가 소리 없이 빠진 CSV는 문제가 없는 사이트처럼 보이기 때문입니다.

예상되는 행 수

거의 모든 사이트에서 행이 나온다고 예상하십시오. SEOReport가 2026년 8월 23일부터 10월 4일까지 감사한 외부 웹사이트 249개에서 보고서 중앙값은 서로 다른 문제(실패 또는 경고 발견 사항) 14건을 표시했고, 사이트의 4분의 1은 17건 이상이었으며, 0건인 사이트는 없었습니다.

사이트별 표시된 문제 수, 외부 사이트 249개, 2026년 8월–10월

이 중앙값에 목록 길이를 곱하면 파일 크기를 무난하게 어림할 수 있습니다. 중앙값에 가까운 사이트 40개라면 약 560행입니다. 한 줄씩 읽기에는 너무 많으므로 area와 finding 열이 있는 것입니다. finding으로 정렬하면 여러 사이트에서 반복되는 문제가 한데 모입니다.

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

같은 발견 사항이 40개 사이트 중 12개에서 실패한다면 먼저 공통 원인을 찾으십시오. 공통 테마, 플러그인, 호스팅 템플릿이 원인이라면 문제 12건이 수정 1건을 12번 적용하는 일로 바뀝니다. 이런 비교가 가능한 것은 파일의 모든 사이트가 같은 방법으로 검사되었고, audited_at 열이 그 시점을 보여 주기 때문입니다. 같은 범위를 AI 채팅 세션으로 다루려면 매번 처음부터 시작하는 대화를 여러 번 따로 열어야 합니다. 그 횟수는 500페이지 사이트에 대한 이 분석에서 계산해 보았습니다.

전체 보고서를 CSV와 함께 보관하기

CSV는 작업용 보기입니다. 기록용으로 보관하거나 사이트 소유자에게 전체 진단을 보내려면 각 보고서를 필요한 형식(pdf, md, txt, 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)

PDF에는 표지, AI 경영진 요약, 카테고리별 분석, 전체 발견 사항이 담겨 있습니다. 각 부분을 읽는 방법은 점수가 매겨진 보고서에 담긴 내용에서 설명합니다.

첫 내보내기 이후에도 같은 사이트를 계속 지켜보려면 PUT /api/v1/monitors로 주간 모니터링에 등록하고, 사이트마다 {"url": ..., "alertEmail": ...}를 보내십시오. 모니터링은 유료 플랜에 포함되어 있고 보고서 크레딧을 사용하지 않으며, 새로운 심각 또는 높은 심각도의 발견 사항이 나타나거나, 심각한 발견 사항이 해결되거나, 점수가 다른 구간으로 이동할 때만 알림 주소로 이메일을 보냅니다.

자주 묻는 질문

스크립트를 다시 실행하면 크레딧이 또 사용됩니까?

이미 보고서가 있는 사이트에는 사용되지 않습니다. 사이트에 이미 보고서가 있으면 API는 새 감사를 실행하는 대신 기존 보고서를 반환할 수 있으므로, 두 번째 CSV를 새로운 측정으로 다루기 전에 audited_at 열을 확인하십시오. 주간 모니터링은 항상 새 감사를 실행하므로, 시간에 따른 변화를 지켜보는 데는 그쪽이 더 적합합니다.

사이트 전체 대신 특정 페이지만 감사할 수 있습니까?

예. 입력 파일에 경로가 포함된 전체 URL을 넣으면 각각 단일 페이지로 감사됩니다. 페이지 감사에는 별도의 시간당 및 일일 한도가 있습니다. 한도에 도달하면 API가 429로 응답하고, 스크립트는 남은 페이지를 API 메시지와 함께 감사되지 않음으로 기록하므로 나중에 다시 실행할 수 있습니다. 사이트 전체를 보려면 홈페이지 주소만 사용하십시오.

감사된 URL이 목록의 URL과 다른 이유는 무엇입니까?

API는 감사 전에 같은 도메인 안에 머무르는 리디렉션을 따라가므로, example.com이 www.example.com으로 감사될 수 있습니다. 다른 도메인으로 가는 리디렉션은 말없이 따라가지 않습니다. 이 경우 감사는 귀하의 주소를 그대로 사용하고 리디렉션을 발견 사항으로 보고합니다. 귀하의 기존 기록과 연결할 때는 site 열을, 결과를 읽을 때는 audited_url 열을 사용하십시오.

스크립트 대신 AI 에이전트가 실행할 수 있습니까?

예. 같은 API 키로 MCP를 지원하는 어떤 에이전트든 MCP 서버에 연결할 수 있으며, 서버는 create_report, get_report_status, get_report를 제공합니다. 설정 방법은 에이전트 설정 가이드에서 다룹니다. 정해진 목록을 일정에 따라 돌리는 데는 스크립트가 더 적합합니다. 매번 똑같이 실행되고 비교할 수 있는 파일을 남기기 때문입니다. 에이전트는 특정 사이트의 발견 사항에 대해 추가 질문을 하고 싶을 때 잘 맞습니다.

CSV에서 Google이 각 사이트를 어떻게 색인했는지 알 수 있습니까?

아닙니다. SEOReport는 감사 시점에 각 사이트가 제공한 내용을 외부에서 검사하며, Search Console 데이터는 읽지 않습니다. Google이 URL에 대해 어떤 결정을 내렸는지는 Search Console에서 확인하고, 사이트의 어떤 부분이 그 원인일 수 있는지는 발견 사항에서 확인하십시오.

사이트의 완전한 진단을 받으세요

근거 기반 보고서와 우선순위 실행 계획을 월간 크레딧 요금제로 받으세요.