인플루언서 검색 API: 팔로워가 아니라 조회수로 크리에이터 고르기

인플루언서 검색 API는 주제와 국가, 팔로워 규모를 보내면 그 조건에 맞는 크리에이터를 찾아서 최근 게시물로 직접 재 보고 순위까지 매겨 돌려줘요. SocialCrawl에서는 GET /v1/prism/creators 하나가 그 일을 해요. 팔로워 수는 프로필에 적힌 숫자일 뿐이에요. 이 API는 크리에이터가 평소 올리는 게시물이 실제로 몇 번 재생되는지를 기준으로 삼아요. 실행하기 전에 드라이런으로 비용을 무료로 확인해요.

인플루언서 검색 툴 대신 API를 쓰는 이유가 있나요?

화면이 있는 인플루언서 검색 툴은 사람이 한 건씩 훑어볼 때 편해요. 검색 결과를 내 대시보드나 리포트, 에이전트에 바로 붙이려면 API가 낫고요. 같은 조건을 매주 다시 돌리거나 이미 가진 후보 목록에 같은 잣대를 대는 일도 API 쪽이 쉬워요.

요청을 보내고 응답을 읽는 방법을 개발자 눈높이에서 다뤄요. 나라별로 TikTok 크리에이터를 찾는 방법은 국가별 TikTok 크리에이터 찾기에 있어요.

팔로워 수 대신 어떤 숫자를 봐야 하나요?

중간 조회수(median_views)를 보세요. 크리에이터의 최근 게시물 조회수를 크기순으로 세웠을 때 가운데에 오는 값이에요. 바이럴 영상 하나가 평균을 크게 끌어올려도 중간값은 거의 움직이지 않아요. SocialCrawl은 고정 게시물과 리포스트를 빼고 최근 게시물 9~12개를 읽어서 이 값을 계산해요.

아래 표는 "home espresso"와 "pour over coffee" 주제로 TikTok과 Instagram을 검색한 결과 중 일부예요. 계정 이름은 지우고 A부터 H까지 이름을 새로 붙였어요.

A는 몇몇 영상이 크게 터진 계정이에요. 평균은 32만인데 보통 올리는 영상은 6천 회 정도 봐요. C는 팔로워가 24만 명이지만 중간 조회수는 1만 1천대예요. 팔로워가 3만 명이 안 되는 D가 더 많이 봐요. 이 표만 봐도 팔로워 수로 조회수를 짐작하기는 어려워요.

고정 게시물은 오래 걸려 있는 대표 영상이라 최근 반응을 흐려요. 모든 지표에서 빠지고 몇 개가 빠졌는지는 각 결과 행의 pinned_excluded에 적혀 있어요.

첫 요청은 어떻게 보내나요?

주제 키워드와 플랫폼, 팔로워 범위, 조회수 하한을 보내면 돼요.

curl "https://www.socialcrawl.dev/v1/prism/creators?keywords=home+espresso,pour+over+coffee&platforms=tiktok,instagram&min_followers=10000&max_followers=250000&min_median_views=5000&country=GB,US&limit=8&max_credits=250&dry_run=true" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

min_median_views=5000은 "보통 올리는 게시물이 5천 회 이상 보이는 사람만"이라는 뜻이에요. country에는 국가 코드를 최대 5개까지 넣어요. 이 요청에는 dry_run=true가 붙어 있어서 크레딧을 쓰지 않고 아무것도 시작하지 않아요. 견적만 돌려줘요.

드라이런 응답은 어떻게 읽나요?

{
  "success": true,
  "data": {
    "estimate": {
      "total": { "min": 29, "expected": 250, "max": 250 },
      "per_delivered": { "min": 3.63, "expected": 72.38, "max": 72.38 },
      "delivered": { "expected": 3, "max": 3 },
      "min_max_credits": 130,
      "answers_in_call": false
    },
    "suggested_max_credits": 725,
    "next_step": "..."
  },
  "credits_used": 0
}

• estimate.total은 이 요청이 쓸 크레딧의 최소, 예상, 최대예요. 예상값은 max_credits를 넘지 않아요.
• estimate.per_delivered는 크리에이터 한 명을 받는 데 드는 크레딧이에요.
• estimate.delivered는 지정한 상한으로 받는 크리에이터 수 예상이에요. 위 응답은 상한 250으로 3명 정도예요.
• suggested_max_credits는 limit까지 채우는 데 넉넉한 상한이에요.
• min_max_credits는 실제 호출이 받아 주는 가장 낮은 상한이에요.
• answers_in_call이 false면 실제 호출은 202로 바로 답하고 뒤에서 이어서 실행해요.

드라이런은 넉넉하게 잡은 견적이에요. 실제 비용은 견적보다 낮게 나오기도 해요. 어떤 경우에도 max_credits는 넘지 않아요. 같은 조건이어도 주제와 국가에 따라 견적이 크게 달라지니 내 요청으로 직접 확인하세요.

상한이 너무 낮으면 실제 호출은 시작하지 않고 400과 max_credits_below_estimate로 거절해요. 이 거절도 무료예요. 응답의 min_max_credits와 suggested_max_credits를 보면 얼마를 승인할지 바로 정할 수 있어요.

실행하면 무엇이 돌아오나요?

같은 요청에서 dry_run만 빼고 보내면 돼요. 이 크기의 요청은 202와 함께 실행 정보(run)를 돌려주고 뒤에서 계속 진행해요. 응답의 data.next.status_url을 호출하면 상태가 바뀔 때까지 최대 25초 기다렸다가 답해요. data.run.status가 completed가 되면 끝난 거예요.

curl "$STATUS_URL" -H "x-api-key: $SOCIALCRAWL_API_KEY"

크리에이터 한 명은 이런 모양이에요. 자리표시 계정이고 필드는 줄였어요.

{
  "account": {
    "key": "tiktok:creator_f",
    "followers": 29815,
    "country": { "value": "US", "source": "author_declared" },
    "metrics": {
      "median_views": 19288,
      "mean_views": 20890,
      "engagement_rate": 0.064,
      "basis": "views",
      "posts_per_week": 7.36,
      "posts_used": 12,
      "pinned_excluded": 2
    }
  },
  "judgments": { "fit": { "p": 0.5 }, "account_kind": "individual_creator" },
  "score": { "value": 0.56 },
  "why": {
    "matched_filters": [
      { "field": "min_median_views", "value": 5000, "measured": 19288 }
    ],
    "judgment_basis": "evidence and 12 walked captions"
  },
  "state": "kept"
}

• fit.p는 이 크리에이터가 요청한 주제와 맞을 확률이에요. 판정기가 낸 값이고 0에서 1 사이예요.
• score.value는 적합도와 참여율, 활동량, 도달 범위를 합쳐서 매긴 순위 점수예요. 기본 정렬 기준이에요.
• engagement_rate는 basis에 적힌 기준으로 계산해요. TikTok은 조회수 기준이고 Instagram은 팔로워 기준이에요.
• median_shares와 median_saves는 플랫폼이 공개하는 경우에만 들어 있어요.
• country는 크리에이터가 프로필에 직접 밝힌 국가이거나 게시물의 지역에서 읽은 값이에요. 어디서 온 값인지 source에 적혀 있어요.

결과 행에서 why부터 읽으세요. matched_filters에는 내가 건 조건과 실제로 잰 값이 나란히 있어서 조건이 제대로 걸렸는지 바로 보여요. 위 예에서는 조회수 하한 5,000에 실제 중간 조회수 19,288이 적혀 있어요. fit이 0.5 근처인 크리에이터는 순위가 높아도 주제가 약하게 맞는 경우예요. 연락하기 전에 why와 fit을 보고 직접 거르세요.

조건은 어떻게 좁히나요?

같은 요청에 필드를 하나씩 더해요. 바꿀 때마다 dry_run=true로 비용부터 확인하세요.

국가를 지정하면 크리에이터의 국가가 확인되고 일치할 때만 결과에 남아요. 국가를 알 수 없는 크리에이터는 기본값으로 빠져요. "해당 국가 크리에이터만 나온다"기보다 "국가가 확인된 크리에이터만 남긴다"로 이해하면 정확해요.

떨어진 후보가 궁금하면 실행 결과를 읽을 때 state=all을 붙이세요. 각 후보에 drop_reason이 적혀 있어요. 주제가 안 맞아 떨어진 후보도 있고 팔로워 범위를 벗어난 후보도 있어요. 조회수 하한에 못 미친 후보도 여기서 보여요.

이미 아는 크리에이터로 시작할 수도 있나요?

요청 방식이 세 가지 더 있어요. 모두 같은 엔드포인트예요.

• 비슷한 크리에이터 찾기. keywords 대신 similar_to=tiktok:creator_f처럼 시드를 1~5개 보내요. 시드의 최근 게시물로 주제를 뽑아서 검색하고 시드 본인은 결과에서 빠져요. 비슷한 계정 하나만 찾는 방법은 비슷한 TikTok 계정 찾기 글에 있어요. 이 방식의 결과는 검토를 시작할 후보 목록으로 보세요. 나온 순서를 그대로 믿지 말고 why와 fit으로 한 번 거르세요.
• 이미 가진 목록에 순위 매기기. POST로 handles(최대 1,000개)나 author_list_id를 purpose: "creator"와 함께 보내면 검색 없이 모든 계정을 같은 잣대로 재서 kept나 dropped 사유와 함께 돌려줘요.
• 문장으로 요청하기. prompt=UK fitness coaches on TikTok with 20k to 200k followers처럼 한 문장을 보내면 필드로 바꿔서 검색해요. 어떻게 해석했는지는 data.request.compiled에서 확인하세요.

제품 소개글을 주면 구매층이 보는 주제를 찾아 주는 campaign 모드도 있어요. 필드 전체는 크리에이터 검색 문서에 정리돼 있어요.

비용 상한과 부족하게 끝나는 경우는 어떻게 다루나요?

max_credits는 이 실행이 쓰는 크레딧의 최대치예요. 그 값에 닿으면 실행이 멈추고 data.run.stopped_because가 max_credits로 바뀌어요. 이미 찾은 크리에이터는 그대로 읽어요. 이어 하려면 data.next.resume_url에 들어 있는 호출을 보내세요. 이미 받은 결과를 다시 사지는 않아요. 더 높은 상한이 담겨 있으면 총 상한이 바뀌는 거니 보내기 전에 한 번 확인하세요.

멈춘 실행이 항상 한 번의 승인으로 끝난다고 장담하지는 않아요. 추가 조회가 더 필요하면 다시 멈추고 그때마다 next_step이 필요한 크레딧을 알려줘요.

limit는 목표예요. 후보가 바닥나면 limit보다 적게 끝나요. 이유는 data.summary.short_reason에 들어 있어요.

• candidates_exhausted는 후보가 바닥났다는 뜻이에요.
• low_yield는 마지막으로 조회한 후보 중 조건을 통과하는 비율이 낮았다는 뜻이에요.

data.summary.more_available이 true면 data.next.more_url로 더 찾아요. false면 이 요청으로는 더 나올 후보가 없으니 키워드나 필터를 바꿔 새로 돌리세요.

결과 전체를 파일로 받고 싶으면 data.next.results_url을 읽으세요. 크리에이터를 한 줄에 하나씩 JSON으로 내려줘요. 실행 결과를 읽는 데는 크레딧이 들지 않아요.

이 API가 하지 않는 일은 무엇인가요?

• 나이, 성별, 인종은 추정하지 않아요. 크리에이터의 개인 특성은 어떤 필드에도 들어 있지 않아요. 국가도 본인이 밝힌 값이나 게시물 지역으로만 정해요.
• 노출이 막힌 계정은 보여주지 않아요. 숨겨 두기로 한 계정은 결과 어디에도 나오지 않아요.
• 연락처는 주지 않고 크리에이터만 찾아요. 이 글의 요청은 이메일이나 전화번호를 돌려주지 않아요. 공개된 비즈니스 이메일을 읽는 방법은 TikTok 이메일 찾기 글을 보세요.
• 정확도를 약속하지 않아요. fit은 판정기의 확률이에요. 순위는 출발점으로 쓰고 why로 직접 확인하세요.

다른 검색 API와 묶어서 쓰고 싶다면 소셜 리스닝 API 글을 보세요. 주제에 새 언급이 생길 때만 알려주는 방법이 나와 있어요.

자주 묻는 질문

인플루언서 검색 API는 팔로워 수와 조회수 중 무엇으로 크리에이터를 고르나요?

둘 다 필터로 걸어요. 순위는 최근 게시물에서 잰 값으로 매겨요. 팔로워 범위는 min_followers와 max_followers로, 보통 게시물의 조회수는 min_median_views로 걸어요. 고정 게시물은 모든 지표에서 빠져요.

드라이런은 정말 무료인가요?

네. dry_run=true를 붙이면 크레딧을 쓰지 않고 아무것도 시작하지 않아요. 예상 비용과 추천 상한, 실제 호출이 받아 주는 가장 낮은 상한을 돌려줘요. 상한이 너무 낮아서 거절되는 max_credits_below_estimate도 무료예요.

크리에이터 한 명을 받는 데 크레딧이 얼마나 드나요?

주제와 국가, 필터에 따라 크게 달라서 한 숫자로 말할 수 없어요. 같은 조건으로 드라이런을 먼저 보낸 뒤 estimate.per_delivered를 읽으세요. 실제 실행은 max_credits를 넘지 않아요.

크리에이터의 나이나 성별도 알 수 있나요?

아니요. 나이, 성별, 인종 같은 개인 특성은 추정하지 않아요. 결과 행에는 팔로워 수, 국가, 게시물에서 잰 지표, 주제 적합도, 계정 유형이 들어 있어요.

요청한 limit만큼 크리에이터가 항상 나오나요?

아니요. limit는 목표라서 후보가 바닥나면 더 적게 끝나요. 그때 short_reason이 이유를 알려주고 more_available이 더 찾을 여지가 있는지 알려줘요.