믿고 올릴 만한 API의 조건은 뭘까요?
측정할 수 있는 세 가지예요. 몰아쳐도 빠르게 유지되고, 돌려주지 못한 데이터엔 요금을 매기지 않고, 문제가 생기면 솔직하게 알려주는 것. 소셜크롤이 이 세 가지를 어떻게 지키는지, 프로덕션 숫자와 함께 보여드려요.
부하에도 빠르게
연산 서버 이전과 업스트림 keep-alive로 대규모 지연을 없앴어요.
빈 응답엔 무과금
빈 페이지는 자동 환불하고, 반복 호출은 0크레딧이에요.
흔들리면 바로 알림
부분 데이터 경고와 실시간 상태 엔드포인트, 문의 없이 확인해요.
속도를 뒷받침하는 숫자
25개 동시 요청으로 몰아친 전후를 프로덕션에서 측정했어요. 원인은 명확했어요. 연산 서버는 US-East에 있고 데이터베이스와 캐시는 런던에 있어서, 호출마다 대서양을 왕복했거든요. 연산 서버를 런던으로 옮기고 업스트림 HTTP keep-alive를 더했어요.
2026-06-30 단일 머신 프로브로 라이브 재확인했어요. 웜 데이터베이스 경로 31ms, 업스트림 부하 지연 1.36배, 429 없음.
다시 불러도 요금은 0
캐시 구간 안에서는 동일한 요청이 캐시에서 0크레딧으로, 약 4배에서 20배 빠르게 돌아와요. 응답에 X-Credits-Used: 0 과 cached: true 가 담겨서 눈으로 확인할 수 있어요.
무조건 최신 데이터가 필요하면 Cache-Control: no-cache 를 보내세요. 강제 새로고침, 엔드포인트별 TTL 조정, 캐시 키 버전 관리까지 지금 다 돼요.
크레딧 작동 방식 보기캐시 구간
- 프로필
- 15분
- 게시물
- 10분
- 댓글
- 5분
- 검색
- 2분
- 분석
- 30분
흔들리면 응답이 먼저 알려줘요
문의를 넣지 않아도 데이터 품질을 솔직하게 알려주는 두 가지 통로예요.
부분 데이터 경고
업스트림 필드가 안 풀리거나 계산 필드가 보정되면, 응답에 data._warnings 가 붙어서 어떤 경로가 실패했는지 그대로 알려줘요. 성공 여부와 크레딧 처리에는 영향이 없고, 전부 정상이면 이 키는 아예 나타나지 않아요.
실시간 상태 엔드포인트
GET /v1/status 는 서킷 브레이커 기준 플랫폼별 상태(operational, degraded, down)와, 공급자 드리프트를 지켜볼 수 있는 현재 업스트림 버전 분포, 그리고 updated_at 타임스탬프를 돌려줘요.
믿고 기댈 수 있는 것
숫자 뒤에 있는 정책이에요.
자동 환불
빈 페이지는 자동으로 환불해서, 돌아오지 않은 데이터에는 요금이 붙지 않아요. 캐시 구간 안의 반복 호출은 0크레딧이에요.
스키마 안정성
변경은 언제나 추가 우선이에요. 기존 필드를 바꾸는 대신 새 엔드포인트와 필드를 더해요. 통합 엔벨로프와 ext 패스스루 덕분에 추가가 기본이고, 호환이 깨지는 변경은 미리 알려드려요.
페이지네이션 정리
빈 페이지는 반복 없이 깔끔하게 끝나고, 안 넘어가는 커서는 잡아내고, 페이지 간 중복은 저희 쪽에서 제거해요. 여러분은 불투명한 next_cursor 만 계속 넘기면 돼요.
정해진 상한
키마다 동시 요청 50개까지예요. 상한을 넘으면 조용히 대기시키지 않고 429로 바로 알려요. 숨기지 않고 공개해서, 미리 설계할 수 있는 한계예요.
“이 페이지의 모든 수치는 여러분의 키로 직접 재현할 수 있는 프로덕션 측정값이에요.”
자주 묻는 질문
원하는 답을 못 찾으셨나요? 팀에 문의하기 또는 아래 AI 에이전트에게 물어보세요