Scraper Hub API

비동기 & 콜백

수집은 시간이 걸립니다. 요청은 즉시 request_id를 돌려주고, 결과는 폴링하거나 콜백(웹훅)으로 받습니다.

흐름

짧은 수집은 폴링(2~5초 간격), 다량/장시간은 콜백을 권장합니다. 콜백을 받더라도 전체 결과는 GET /requests/{id}로 가져옵니다(콜백 본문엔 요약만).

폴링

상태가 pending → running → done | failed | cancelled로 바뀝니다. running 중에는 progress와 elapsed_ms(경과)로 진행 상황을 볼 수 있습니다.

# done 까지 반복 조회 curl https://scraper.conbus.co.kr/api/v1/requests/42 -H "Authorization: Bearer YOUR_API_KEY" # running → { "status":"running", "progress":{"count":12,"phase":"list"}, "elapsed_ms":8200 } # done → { "status":"done", "result_count":30, "duration_ms":42100, "duration_sec":42.1, "items":[ ... ] }

수집 소요 시간

완료(또는 실패/취소)된 요청은 허브가 측정한 수집 소요 시간을 함께 돌려줍니다 — 워커가 작업을 가져간(started_at) 시점부터 결과 제출(finished_at)까지입니다.

소요 시간은 큐 대기 시간을 제외한 순수 수집 시간입니다(요청 생성 created_at → 수집 시작 started_at 사이가 대기 시간). 재시도가 있었다면 마지막 시도 기준입니다.

긴 기간 요청 (기간 나누기)

네이버 블로그·뉴스·카페(공개) 검색에서 최신순으로 한 달이 넘는 기간을 요청하면, 허브가 기간을 달 단위 조각으로 나눠 여러 수집 서버에서 수집한 뒤 합쳐서 돌려줍니다. 요청 번호와 응답 형식은 같습니다.

이미 수집한 기간은 원장으로 답함

최신순으로 기간(start_date)을 준 요청에서, 허브가 같은 검색 조건으로 이미 끝까지 수집한 날짜는 플랫폼에 다시 묻지 않고 허브의 수집 원장으로 답합니다. 요청 번호·응답 형식은 같고, 나머지 날짜는 지금처럼 수집합니다.

{ "post_id":"blogid/224000000000", "title":"...", "posted_at":"2026-08-10T10:00:00+09:00", ..., "extra":{ ..., "ledger_at":"2026-09-25 12:00:00" } }

덜 모은 기간 경고 (warnings.capped_periods)

플랫폼 검색 깊이 상한(예: 네이버 블로그 검색 조건당 약 1,000건)이나 페이지 상한에 걸려 그 기간에 글이 더 있을 수 있는 경우, 완료 응답에 warnings.capped_periods 가 붙습니다(네이버 블로그·뉴스·카페 검색, 디시인사이드, 뽐뿌).

"warnings": { "capped_periods": [ { "start_date": "2026-07-01", "end_date": "2026-07-31", "reason": "platform_cap" } ] }

reason 은 platform_cap(플랫폼 상한) · max_pages(페이지 상한)이고, 기간을 나눈 요청은 조각이 시간 초과·차단으로 덜 모았을 때 timed_out · blocked 도 올 수 있습니다. 더 필요하면 그 기간을 더 짧게 나눠 다시 요청하세요 — 허브가 알아서 다시 수집하지는 않습니다.

차단으로 멈춤·상세 실패 (warnings.blocked · warnings.detail_failed)

수집 중 사이트가 차단·캡차(자동입력 방지) 신호를 보내면 그 자리에서 멈추고 더 요청하지 않습니다 — 다시 시도·다른 IP 우회·캡차 풀이를 하지 않습니다(모든 채널, 2026-10-12). 그때까지 받은 글은 결과에 담기고 warnings.blocked = true 가 붙습니다 — 결과가 중간까지만이라는 뜻입니다. 받은 글이 하나도 없으면 완료가 아니라 failed 이고 허브도 다시 시도하지 않습니다. 같은 요청을 바로 다시 보내지 말고 시간을 두세요. 본문·댓글 상세만 막힌 경우에는 그 뒤 글이 목록 값(제목·요약)으로 담깁니다. 네이버 뉴스는 언론사 원문 사이트가 막으면 그 사이트의 기사만 요약으로 두고 다른 기사는 계속 받습니다.

본문·댓글 상세를 요청했는데 글 페이지를 읽지 못한 글이 있으면 그 수가 warnings.detail_failed 이고, 그 글들은 목록 값(제목·요약)으로 담기며 extra.detail_error 에 이유가 있습니다(네이버 카페 공개 검색 — 회원 전용 글은 실패가 아니라 extra.member_only = true).

"warnings": { "blocked": true, "detail_failed": 12 }

요청 취소 (force-cancel)

실수로 시작한 수집을 강제로 중단합니다. 같은 API 키로 발급한 요청만 취소할 수 있습니다.

POST /api/v1/requests/{id}/cancel
curl -X POST https://scraper.conbus.co.kr/api/v1/requests/42/cancel \ -H "Authorization: Bearer YOUR_API_KEY"

응답 (200)

{ "success":true, "data":{ "request_id":42, "channel":"dcinside", "status":"cancelled", "cancelled_at":"2026-06-16T09:01:30+09:00" } }

동작 / 규칙

콜백(웹훅)

callback_url 지정 시 완료/실패에 아래 요약 알림이 POST됩니다.

POST {your callback_url} Content-Type: application/json { "event":"request.completed"|"request.failed", "request_id":42, "channel":"dcinside", "status":"done", "result_count":30, "external_ref":"my-001", "result_url":"https://scraper.conbus.co.kr/api/v1/requests/42" }

결과 확인 (인증은 여기서)

콜백 자체엔 서명이 없습니다 — 트리거(알림)로만 쓰고, 실제 데이터는 콜백 안의 result_url(= GET /requests/{id})을 본인 API 키로 호출해 받으세요. 인증·검증은 그 호출에서 이뤄집니다(키가 맞아야 200, 본인 요청만 조회 가능).

# 콜백 받으면 result_url 을 키로 조회 curl https://scraper.conbus.co.kr/api/v1/requests/42 -H "Authorization: Bearer YOUR_API_KEY"

재시도

콜백이 2xx를 반환하지 않으면 자동 재시도합니다 — 최대 5회, 점증 백오프(60s → 5m → 15m → 1h). 그래도 실패하면 중단되며, 결과는 폴링으로 받을 수 있습니다.

플레이그라운드에서 직접 시험해 보세요.