인증과 엔드포인트 구분
조회에는 GET 요청과 Authorization: Bearer <key> 또는 X-API-Key: <key> 헤더를 사용합니다. 두 방식 모두 지원되므로 하나를 선택할 수 있습니다. 키는 redditlistening.com 계정에 속하며 다른 도메인의 키로 대체할 수 없습니다. 계정 패널의 Secure HttpOnly 세션 쿠키와 조회용 키는 별개입니다. 로그인 쿠키나 비밀번호를 데이터 요청의 API 키 대신 보내지 마세요.
/v1/search, /v1/posts, /v1/comments에서 사용할 수 있는 조건은 q, subreddit, author, kind, from, to, min_score, limit, page입니다. kind의 값은 post 또는 comment입니다. posts와 comments는 레코드 종류를 제한하며 id를 요구하지 않습니다. 특정 식별자로 한 항목을 찾으려면 /v1/item?id=...를 사용하세요. 이 경로의 매개변수는 id입니다. 문서에 없는 사용자 지정 검색 조건은 제공되지 않습니다.
/v1/subreddits는 prefix와 limit만 받습니다. 날짜 조건이나 page를 붙여 본문을 검색하는 경로가 아니며, 집계 수도 전체 범위에서 정확하다고 보장하지 않습니다. /v1/status는 공개되어 있고 무료입니다. 고정된 서비스 범위 설명과 HTTP 서버의 응답을 확인할 뿐, 검색 백엔드의 상태나 특정 기록의 존재, 아카이브 접근 가능성을 검사하지 않습니다. 이를 수집 작업의 성공을 보증하는 지표로 쓰지 마세요.
날짜와 반환 데이터 읽기
from과 to는 UTC 기준 YYYY-MM-DD 날짜로 지정하며 created_utc 필드에 적용됩니다. to는 해당 날짜 전체를 포함합니다. 오늘의 UTC 날짜를 넣었다면 오늘 자정의 한 시점만이 아니라 오늘 하루 전체가 범위에 포함됩니다. 이 시간은 레코드가 작성된 때입니다. 배낭을 구매하거나 사용한 날짜, 제품이 고장 난 날짜를 직접 검색하는 조건으로 해석해서는 안 됩니다.
본문 쿼리의 limit은 1–100, page는 1–100입니다. 반환 순서는 _doc이며 시간순, 관련성순, 점수순이 아닙니다. min_score는 최저 점수 조건이지 정렬 방식이 아닙니다. 받은 레코드를 로컬에서 날짜순으로 정리할 수 있지만, 아직 받지 못한 글의 위치나 중요도를 알게 되는 것은 아닙니다. 날짜 분할과 전체 페이지 순회 역시 빠짐없는 수집을 증명하지 못합니다.
응답은 서버에서 조립한 스레드 트리가 아닌 평면 레코드입니다. parent_id 또는 link_id가 있으면 로컬에서 연결할 수 있으나 이 둘은 조회 필터가 아닙니다. 필드 누락, null, 빈 문자열을 구분해 처리하세요. 총수 관계가 eq이면 정확한 값, gte이면 하한, unknown이면 신뢰할 총수가 없다는 뜻이며 값이 null일 수 있습니다. 이 정보는 아카이브의 전체 범위를 보장하지 않습니다.
오류와 재시도 기록
HTTP 400은 잘못된 요청, 401은 없거나 유효하지 않은 키, 402는 부족한 크레딧, 429는 요청 빈도 제한입니다. 400에서는 날짜 형식과 허용된 조건을, 401에서는 키를, 402에서는 이 도메인의 잔액을 확인하세요. 429 뒤에는 기다렸다가 재시도합니다. 같은 요청을 빠르게 반복한다고 누락된 대화가 채워지거나 조사 자료의 대표성이 높아지는 것은 아닙니다.
잘못된 요청은 과금되지 않고, 원본 조회 시스템의 오류에서는 예약한 크레딧이 반환됩니다. 빈 응답도 성공한 조회라면 1크레딧입니다. 서버가 처리를 끝낸 뒤 클라이언트가 응답을 받지 못한 경우에는 이미 과금되었을 수 있습니다. 성공한 재시도는 별도 크레딧을 사용하므로 수신 실패와 실제로 받은 빈 결과를 작업 기록에서 구분하세요.
backpack과 BuyItForLife를 조사할 때는 쿼리, 실제 조회 시점, 포함한 글, 제외 이유를 로컬에 남겨 두세요. 중복 제거는 확보한 자료의 중복을 줄이는 작업이며 누락된 자료를 복원하지 않습니다. 댓글 수와 작성자 수, 제품 경험 수는 서로 다른 단위입니다. 집계 전에 어떤 단위를 세는지 정하고, 분석 결과를 제공자의 자동 평가처럼 표시하지 마세요.
