SNS 검색 엔진 API 한 번 호출로 여러 SNS를 20크레딧에 검색해요

SNS 검색 엔진은 검색어 하나를 여러 플랫폼에 동시에 보내고 제각각이던 응답을 한 목록으로 묶어 돌려주는 검색이에요. SocialCrawl에서는 GET /v1/search/everywhere 한 번이면 되고 비용은 검색당 20크레딧이에요.

주제별로 글, 영상, 댓글을 모으려는 개발자와 AI 에이전트가 쓰는 호출이에요. 사람을 찾거나 계정을 조회하는 데는 맞지 않아요.

SNS 검색 엔진이 뭔가요?

플랫폼마다 따로 검색 API를 부르지 않고 검색어 하나로 Reddit, X, YouTube, TikTok, Instagram, Threads, LinkedIn, Hacker News, 웹을 동시에 검색하는 방식이에요. 결과는 순위대로 정렬되고 비슷한 글은 하나로 합쳐져 한 목록으로 돌아와요 (검색 문서).

플랫폼별 검색은 응답 모양이 모두 달라서 파서를 따로 짜야 해요. 통합 검색에서는 Reddit 글과 TikTok 영상이 필드가 같은 행으로 오니까 한곳에서 정렬하고 거르면 돼요.

여러 SNS를 한 번에 검색하려면 어떻게 호출하나요?

API 키와 검색어를 넣어 /v1/search/everywhere에 GET 요청을 보내면 돼요. period로 기간을, format=compact로 가벼운 응답을 고르세요.

curl "https://www.socialcrawl.dev/v1/search/everywhere?query=pour%20over%20coffee&period=7d&format=compact&limit=20&deadline_s=25" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

최근 7일 안에서 상위 20개 행을 최대 25초까지 기다려 받아요. 실행 전에 가격과 계획을 보고 싶다면 dry_run=1을 붙이세요. 비용은 0이고 검색할 소스와 예상 비용, 환불 규칙이 돌아와요.

자주 쓰는 파라미터예요.

전체 목록은 파라미터 문서에 있어요.

응답에는 어떤 정보가 들어 있나요?

format=compact의 행에는 플랫폼, 콘텐츠 종류, URL, 작성자, 언어, 날짜, 좋아요·댓글·조회수, 280자로 줄인 본문, 댓글 최대 3개가 들어 있어요. 줄여서 보면 이래요.

{
  "id": "tt_abc123",
  "platform": "tiktok",
  "record_type": "video",
  "url": "https://www.tiktok.com/@.../video/...",
  "text": "...",
  "likes": 1223,
  "views": 9347,
  "comments": 10,
  "pct": 0.5,
  "published_at": "2026-10-27"
}

pct는 같은 플랫폼, 같은 종류의 행 안에서 반응이 어느 정도인지 보여 주는 백분위예요. 0.5면 그 플랫폼에서 중간쯤이에요. comments는 댓글 수예요. 댓글 본문이 함께 오면 comment_items에 담겨요.

compact 응답은 20행에 20KB 정도예요. 같은 검색의 classic 응답은 수백 KB라서 에이전트에는 compact를 권해요.

검색 한 번에 크레딧이 얼마나 드나요?

검색 한 번은 20크레딧이에요. 소스가 몇 개 응답하든, 댓글이 몇 개 붙든 같아요. API 키로 한 검색은 실행 기록으로 저장돼요. 저장된 기록은 다시 읽어도 무료예요.

keywords의 문구 하나, languages의 언어 하나가 각각 20크레딧짜리 검색이에요. 키워드 3개면 60크레딧이라서 여러 개를 보낼 때는 먼저 dry_run=1로 확인하세요. 크레딧 규칙 전체는 크레딧 문서에 있어요.

어떤 플랫폼까지 검색되나요?

기본으로 Reddit, X, YouTube, TikTok, Instagram, Threads, LinkedIn, Pinterest, Hacker News, GitHub, Polymarket, Rumble, 웹을 검색해요. 검색어에 한글이 있으면 Naver가 더해져요. Facebook은 include=facebook으로 요청할 때, Bluesky·뉴스·Quora는 platforms에 직접 적을 때만 돌아요.

검색 범위는 이 목록까지예요. 더 긴 기간이나 더 많은 플랫폼이 필요하면 플랫폼마다 여러 페이지를 읽는 Discover가 맞아요. 다른 서비스와의 비교는 멀티 플랫폼 검색 API 비교에 정리해 뒀어요.

depth=quick은 X, YouTube, TikTok, 웹만 10초 제한으로 검색해요. 비용은 똑같이 20크레딧이에요. 에이전트가 한 턴 안에 빨리 답해야 할 때 쓰세요. Reddit은 빠져요.

검색이 느리거나 일부만 끝나면 어떻게 되나요?

소스마다 속도가 달라서 모든 소스가 답하기 전에 응답이 올 때가 있어요. 이때 상태는 두 가지인데, 어느 쪽이든 다시 결제되지 않아요.

deadline_s가 지났는데 검색이 아직 돌고 있으면 status: "running"과 status_url이 담긴 200이 와요. 검색은 계속 진행되고 결과가 저장돼요. 상태가 completed가 될 때까지 status_url을 읽으세요. 같은 요청을 다시 보내면 새 검색이 되니 보내지 마세요.

일부 소스가 실패하면 partial로 끝나요. 마지막 상태여서 더 올 결과는 없어요. 이유는 stopped_because에 나와요. upstream_failures라면 응답하지 못한 플랫폼이 있었던 경우예요. 응답한 소스의 행은 그대로 받아요. 다시 검색하거나 next의 드라이런 URL로 실패한 소스를 뺀 검색을 해 보세요.

deadline_s는 쓰는 클라이언트의 타임아웃보다 짧게 두세요. 에이전트 도구는 25초를 써요.

SNS 검색 엔진으로 할 수 없는 건 뭔가요?

읽는 건 공개 데이터뿐이에요. 알아 둘 한계는 이래요.

• 결과는 호출한 순간 각 플랫폼의 자체 검색이 내놓은 것이라서 몇 분 차이로도 달라져요. 고정된 결과가 필요하면 저장된 기록을 보세요.
• 기간은 받는 행을 제한할 뿐이에요. 플랫폼이 내주지 않는 오래된 글까지 끌어오지는 못해서 먼 과거 기간은 결과가 적을 수 있어요.
• 소스마다 그 플랫폼 검색 결과를 한 페이지씩만 읽어요. 전체 아카이브를 훑지는 않아요. 플랫폼마다 여러 페이지가 필요하면 Discover를 쓰세요.
• 비공개, 로그인이 필요한 글, 삭제된 글은 읽지 않아요.
• 위에서 말한 플랫폼만 다루고 웹 전체를 크롤링하지는 않아요.

자주 묻는 질문

SNS 검색 엔진이 뭔가요?

검색어 하나를 여러 플랫폼에 동시에 보내고 한 목록으로 돌려주는 검색이에요. SocialCrawl에서는 GET /v1/search/everywhere가 Reddit, X, YouTube, TikTok, Instagram, Threads, LinkedIn 등을 한 번에 검색해요. 행의 필드가 모두 같아서 플랫폼마다 파서를 만들지 않아도 돼요.

사람이나 계정을 찾는 기능인가요?

아니에요. 주제를 넣으면 그 주제의 글, 영상, 댓글을 찾아 줘요. 사용자 이름이나 특정 개인을 조회하는 기능은 없어요.

검색 한 번에 비용이 얼마인가요?

응답한 소스 수와 상관없이 20크레딧이에요. 드라이런, 저장된 기록 읽기, 공유 캐시 응답은 무료예요. 적어도 한 소스가 응답했는데 결과가 0건이거나 모든 소스가 실패하면 0크레딧이에요. 결과는 있지만 호출한 소스의 과반이 실패하면 10크레딧만 내요.

응답의 partial은 무슨 뜻인가요?

실행이 끝났지만 일부 소스가 실패했다는 뜻이에요. 더 올 결과는 없어요. 응답한 소스의 행은 그대로 받아요. stopped_because를 확인하고 다시 검색하거나 실패한 소스를 빼고 검색하세요.

모든 SNS를 한 번에 검색할 수 있나요?

주요 SNS와 웹이 들어 있는 기본 묶음은 한 번에 검색돼요. platforms로 좁힐 수 있고 include=facebook을 붙이거나 Bluesky·뉴스·Quora를 직접 적으면 넓어져요. 다만 모든 SNS나 웹 전체를 보지는 않아요.