q, subreddit, author, kind, from, to, min_score, limit, page
GET
/v1/posts
q, subreddit, author, kind, from, to, min_score, limit, page
GET
/v1/comments
q, subreddit, author, kind, from, to, min_score, limit, page
GET
/v1/item
id
GET
/v1/subreddits
prefix, limit
GET
/v1/status
—
쿼리 매개변수
매개변수
값 / 유형 / 범위
q
text
subreddit
keyword
author
keyword
kind
post | comment
from
ISO date
to
ISO date
min_score
integer
limit
1–100
page
1–100
id
item ID
prefix
subreddit prefix
조회 경로와 인증 방식
/v1/search 엔드포인트는 게시물과 댓글을 통합 검색합니다. /v1/posts와 /v1/comments는 각각 해당 유형의 데이터만 반환합니다. /v1/item은 고유 식별자를 통해 특정 항목의 세부 정보를 조회하며, /v1/subreddits는 접두사 기반 하위 커뮤니티 목록을 제공합니다. 각 엔드포인트는 자체적인 필터 범위를 지원합니다.
기본 주소는 https://api.redditscraping.com이며 조회에는 GET을 사용합니다. /v1/item?id=...에서 id를 지정하고, posts나 comments에는 id를 보내지 마세요. /v1/subreddits?prefix=...의 prefix는 이름의 시작 부분을 지정하며 limit으로 요청 결과 수를 제한할 수 있습니다. 커뮤니티 집계 건수가 전체 범위에서 항상 정확하다고 가정하지 마세요. 특정 응답에 나온 숫자가 아카이브 전체의 완전한 포함 범위를 증명하지는 않습니다.
데이터 조회는 Authorization: Bearer YOUR_API_KEY와 X-API-Key: YOUR_API_KEY 중 어느 헤더로도 인증할 수 있습니다. 실제 키를 URL이나 공개 예제에 넣지 말고 서버의 비밀 설정에서 읽으세요. 계정 패널의 Secure HttpOnly 세션 쿠키는 별도 용도이며 조회 헤더를 대신하지 않습니다. 키는 이 도메인 전용입니다. 다른 브랜드에서 발급한 키가 이 계정에 대한 권한을 제공하지는 않습니다.
GET /v1/status는 공개 경로이며 크레딧을 사용하지 않습니다. 고정된 서비스 범위 안내와 HTTP 애플리케이션이 응답한다는 사실을 보여 줍니다. 아카이브 소스의 상태, 사용 가능한 기록, 쿼리 실행이나 계정 잔액을 검사하지는 않습니다. 따라서 status가 성공했다고 실제 조회도 성공한다고 판단하지 마세요. 데이터 요청 자체의 응답 상태와 내용을 별도로 처리하고, 필요한 기록을 받았는지 클라이언트에서 확인해야 합니다.
필터와 페이지 결과 해석
검색, 게시물 및 댓글 쿼리에는 q, subreddit, author, kind, from, to, min_score, limit, page를 사용할 수 있습니다. kind 값은 post 또는 comment입니다. 날짜는 UTC 기준 YYYY-MM-DD 형식이며 to로 지정한 날짜도 범위에 포함됩니다. min_score는 최소 점수 필터이고 정렬 옵션이 아닙니다. parent_id와 link_id는 지원되는 조회 필터가 아니므로 이 값으로 관계 검색을 요청할 수 있다고 생각하지 마세요.
한 번의 요청은 최대 100개 기록이며 한 쿼리는 최대 100페이지입니다. 페이지마다 별도 요청이 필요합니다. 결과는 아카이브 문서 순서이므로 시간, 관련도나 점수에 따라 정렬되지 않습니다. 기간을 작게 나누는 방식은 작업을 정리할 수 있지만 전체 기록의 수집이나 중복 제거를 보장하지 않습니다. 사용한 필터와 저장한 페이지를 클라이언트 작업 기록에 남겨 실제 받은 범위를 설명하세요.
전체 건수는 페이지 수가 아닙니다. eq는 정확한 건수, gte는 하한, unknown이나 null은 신뢰할 만한 전체 건수가 없음을 의미합니다. 정확한 전체 건수가 있어도 클라이언트가 전부 저장했다는 증거가 되지는 않습니다. 응답은 평면 기록입니다. 읽기나 개수 세기에는 트리가 필요하지 않으며, 관계를 살펴볼 때만 존재하는 parent_id나 link_id로 로컬에서 묶을 수 있습니다. 이 선택적 처리는 누락된 부모나 댓글을 복원하지 않습니다.
오류와 과금 구분
HTTP 400은 요청의 형식이나 매개변수를 확인해야 하는 경우입니다. HTTP 401은 키가 없거나 유효하지 않음, HTTP 402는 잔액 부족, HTTP 429는 요청 속도 제한을 뜻합니다. 원인에 맞게 조건이나 키를 수정하고, 속도 제한에서는 요청을 늦추세요. 모든 오류에 같은 즉시 재시도를 적용하면 문제를 해결하지 못한 채 작업만 반복할 수 있습니다. 조회 전에 오류별 처리 방식을 정해 두세요.
성공한 조회는 빈 결과도 크레딧 한 개를 사용합니다. 잘못된 요청은 차감하지 않고 상위 소스 오류에서는 예약된 크레딧을 돌려줍니다. 그러나 클라이언트 연결이 끊어져도 서버에서는 유료 요청이 성공했을 수 있습니다. 이후 성공한 재시도에는 별도 크레딧이 듭니다. 화면에 보이는 통신 오류만으로 비용이 발생하지 않았다고 결론 내리지 말고, 저장과 재시도 결정을 이 차이에 맞춰 설계하세요.
