인증과 오류 코드
보호된 조회에는 Authorization: Bearer YOUR_API_KEY 또는 X-API-Key: YOUR_API_KEY를 사용할 수 있습니다. 두 헤더를 모두 지원합니다. /v1/status는 공개이며 키가 필요 없습니다. HTTP 401은 키가 없거나 유효하지 않다는 뜻으로, 계정 패널의 로그인 세션 만료와는 별개입니다. 키와 잔액은 subredditapi.com 전용이며 다른 브랜드의 계정과 공유되지 않습니다. 실제 키를 공개 코드나 연구 데이터 파일에 넣지 마세요.
HTTP 400은 잘못된 요청, 402는 잔액 부족, 429는 요청 속도 제한입니다. 400이면 매개변수를 수정하고 401이면 키를 확인하세요. 402이면 작업을 멈추거나 충전하고, 429이면 기다린 뒤 다시 시도하세요. 유효한 키만 있다고 요청 성공이나 특정 기록의 존재가 보장되지는 않습니다. 최소 유료 충전은 $50이며 가입과 키 표시에 결제가 필요한 것은 아닙니다. 응답 코드를 실제 결과와 함께 기록하세요.
성공한 조회는 빈 결과도 1크레딧을 사용합니다. 잘못된 요청은 차감하지 않고 상위 데이터 소스 실패는 예약 크레딧을 반환합니다. 클라이언트 통신 오류는 서버 실패와 같지 않으며 과금된 성공이 이미 있었을 수 있습니다. 성공한 재시도에는 새 크레딧이 필요합니다. /v1/status는 무료지만 정적 안내와 HTTP 응답만 보여 주고 검색 상태나 기록의 존재를 검사하지 않습니다. 이를 조회 가능성이나 전체 범위의 증거로 사용하지 마세요.
경로별 검색 조건
GET /v1/search는 q, subreddit, author, kind, from, to, min_score, limit, page를 지원합니다. kind는 post 또는 comment입니다. GET /v1/posts와 GET /v1/comments는 해당 종류의 기록을 가져오며 id가 필요하지 않습니다. 알려진 한 기록에는 GET /v1/item과 id를 사용하세요. 서로 다른 두 커뮤니티를 비교하려면 별도 요청을 보내고 선택한 나머지 조건을 같게 유지합니다. 여러 이름을 한 subreddit 값으로 보낼 수 있다고 가정하지 마세요.
from과 to는 UTC 달력 날짜를 YYYY-MM-DD로 지정하며 to 날짜도 포함합니다. limit와 page는 1부터 100까지이고 요청당 100개 기록, 쿼리당 100페이지가 한도입니다. min_score는 필터이며 점수 정렬이 아닙니다. 응답은 시간순, 관련도순, 점수순이 아닌 문서 순서로 옵니다. 같은 조건이 두 커뮤니티의 범위나 표본 대표성을 같게 만들지는 않습니다. 필터와 원본 응답을 함께 저장해 비교 방법을 설명하세요.
GET /v1/subreddits는 prefix와 limit로 커뮤니티 이름을 찾습니다. 이 경로는 본문 접두어 검색이나 author, kind 필터가 아닙니다. 이름의 순서가 알파벳순이거나 집계가 전역적으로 정확하다고 보장되지 않습니다. 조회 총수의 eq는 정확, gte는 하한, unknown은 알 수 없음을 뜻하며 총수가 null일 수 있습니다. 정확한 총수도 모든 일치 기록이 클라이언트에 저장되었다는 증거가 아닙니다. 범위의 불확실성을 방법 기록에 남기세요.
평면 레코드와 비교의 한계
응답은 평면 레코드이며 서버가 만든 완전한 대화 트리가 아닙니다. parent_id나 link_id가 있으면 로컬로 관계를 묶을 수 있지만 부모 기록이나 앞선 대화가 없을 수 있습니다. 이 두 필드는 요청 필터가 아닙니다. 맥락이 부족한 인용은 그 한계를 표시하고 없는 기록을 추정으로 채우지 마세요. 관계를 연결할 수 없었던 레코드를 별도로 보관하면 후속 분석에서 제외 이유를 설명하는 데 도움이 됩니다.
독립적인 과거 아카이브는 Reddit OAuth, 게시, 투표, 비공개 메시지나 실시간 모니터링을 제공하지 않습니다. 과거 기록이라고 불변 스냅샷이 되는 것도 아닙니다. 같은 쿼리가 미래에 같은 결과나 순서를 줄 것이라고 가정하지 마세요. 실제 응답, 요청 조건, 수신 시각과 로컬 분석 규칙을 보관하면 같은 입력을 다시 처리할 수 있습니다. 이는 자신의 분석을 검증하는 절차이며 원격 기록의 보존이나 완전성을 증명하지 않습니다.
작은 예시는 /v1/search?q=soil&subreddit=gardening&limit=3입니다. 최대 3개를 요청할 뿐 결과의 존재나 대표성을 보장하지 않습니다. 단어 빈도, 주제 라벨, 감정 점수는 연구자가 받은 텍스트에서 직접 계산할 수 있지만 API가 제공하는 분석 결과가 아닙니다. 누락 텍스트, 언어 혼합, 제외 기준과 정규화 방법을 기록하세요. 문서와 가격 페이지를 함께 참고해 두 커뮤니티의 조회 예산을 잡고 성공한 빈 결과 및 재시도도 포함하세요.
