API 문서

엔드포인트 하나, op 필드 하나. 모든 엔드포인트가 같은 요청 형식을 씁니다.

빠른 시작

무엇이 돌아오는지 먼저 보고 싶다면 Playground에서 바로 확인하세요. 이 페이지를 먼저 읽을 필요는 없습니다.

가입해서 키를 받은 뒤(무료 플랜 100 크레딧) 다음을 실행하세요:

curl -X POST https://widefetch.com/v1/call \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"google.search","params":{"keyword":"vector database"}}'

인증

Authorization: Bearer sk_…. 키는 콘솔에서 발급되며 전체 값은 발급 순간 한 번만 보입니다(해시만 저장).

폐기는 즉시 적용됩니다. 키가 유출되면 폐기하고 새로 발급하세요.

호출하기

POST /v1/call

필드	타입	설명
op	string	호출할 엔드포인트, 아래 표 참고
params	object	해당 엔드포인트의 파라미터

제한된 동기 처리: 약 25초 안에 끝나는 호출은 결과를 바로 반환합니다. 더 걸리면 status: "running"과 request_id를 반환하니 그것으로 폴링하세요. 브라우저 기반 엔드포인트(executor: browser)는 오래 걸리는 경우가 많고, http와 api는 보통 1~2초 안에 돌아옵니다.

{
  "request_id": "req_7Qn1vK…",
  "status": "done",          // done | running | failed
  "outcome": "ok",
  "credits_charged": 1,      // 0 when the call failed
  "timing": {
    "queued_ms": 400,
    "ran_ms": 8100,
    "attempts": 1            // >1 means it was retried
  },
  "result": { "items": [ … ] }
}

폴링

GET /v1/requests/{request_id}

응답 형식은 위와 같습니다. 2초마다 폴링하고 5초까지 간격을 늘리세요.

과금 규칙

실패한 호출은 무료입니다. 캡차, 속도 제한, 타임아웃, 매핑되지 않은 응답은 저희 책임으로 자동 환불됩니다.
결과 없음은 과금됩니다. "찾지 못함"은 실패가 아니라 답이며, 비용은 이미 발생했습니다.

과금되는 outcome

no_resultsokverified_page

과금되지 않는 outcome

bad_paramscancelledcaptchaclaim_timeoutneeds_mappingnot_configuredrate_limitedtimeouttransient

목록에 없는 outcome은 모두 무료입니다. 기본값을 과금으로 두면 저희 장애가 고객의 청구서가 되기 때문입니다.

엔드포인트

op	credit	파라미터	설명
brave.search	1	keyword*, limit, region, language	웹 검색 결과: 제목, URL, 스니펫. 빠르고 대량 병렬 호출에 적합합니다.	실행해 보기
github.repo	1	repo*	GitHub 저장소 하나: 스타, 포크, 열린 이슈, 언어, 라이선스, 토픽.	실행해 보기
github.search	1	query*, sort, order, limit	GitHub 저장소 검색. 스타, 포크, 최근 업데이트 순으로 정렬.	실행해 보기
google.search	1	keyword*, limit, language, region	Google 자연 검색 결과: 제목, URL, 출처 도메인, 스니펫.	실행해 보기
google.trends	1	keyword*, region	Google 트렌드 검색 관심도: 지난 2년간의 주간 시계열(0–100).	실행해 보기
hn.comments	1	keyword*, limit, sort, since	Hacker News 댓글 검색: 원문, 작성자, 소속 게시물.	실행해 보기
hn.item	1	id*, comments	Hacker News 스레드 전체: 본문과 모든 댓글.	실행해 보기
hn.search	1	keyword*, limit, sort, since, min_points	Hacker News 게시물: 제목, 링크, 작성자, 점수, 댓글 수, 시간.	실행해 보기

오류 코드

코드	의미	조치
400	잘못된 파라미터 또는 존재하지 않는 op	요청을 수정하세요. 과금 없음
401	키가 틀렸거나 폐기됨	다른 키 사용
402	크레딧 부족	업그레이드하거나 월간 초기화를 기다리세요
403	이 키의 허용 목록에 해당 op가 없음	응답의 `error` 필드 확인
429	속도 또는 동시 실행 한도 초과	간격을 두고 재시도. 과금 없음
502	저희 쪽 또는 업스트림 문제	재시도. 과금 없음

속도 제한

키마다 기본 분당 60회이며 동시 실행 수에 한도가 있습니다. 한도를 넘으면 대기열이 아니라 429가 반환됩니다.

더 높은 한도가 필요하면 문의하세요.