Universal Search Creators API
TikTok, Threads, Instagram에서 주제에 맞는 크리에이터를 핸들 기준으로 합쳐 팔로워 점수로 순위를 매긴 목록 하나로 반환합니다. country=를 주면 그 시장에서 주제를 다루는 크리에이터만 남깁니다.
GET /v1/search/creatorsUniversal Search Creators API는 언제 쓰나요
게시물이 아니라 크리에이터 계정을 찾을 때 사용하세요. 중남미, 스페인, 브라질 시장 하나로 좁히려면 country=를 더하세요. 게시물 전반은 search/everywhere가 맞습니다.
API 레퍼런스 영문 원문
Fans a niche query across TikTok user search, Threads user search, and Instagram profile search by default, then merges matching creators into one deterministically ranked list. Ranking is a published formula of query relevance, follower scale, and verification. No LLM rerank by default. Pass sources=youtube, twitter, or facebook (or a CSV of any of the six) to add those profile searches; omitting sources keeps the original three-platform walk so existing callers do not change. Pass brief= (what you are looking for, in your own words) to have the first 40 creators judged from their name, handle and bio: each gets brief_match ({ fits_brief, account_kind, account_kind_confidence, brief_score }) and the list is re-ranked so creators who post about your brief lead, with brands, shops, academies and repost pages below them; data.brief reports what was judged and the ranking version. relevance=filter also drops creators that do not fit and lists them in data.brief.dropped_ids. Pass country (CL, AR, MX, CO, PE, EC, UY, ES, BR) to find the creators who post about your query in that market, on TikTok and Instagram, instead of searching account names. The market's own name is added to your query (inteligencia artificial with CL searches inteligencia artificial chile, returned as data.country.by_source.<source>.query_sent). On TikTok the result is the creators behind the videos whose own region is the market and whose text is about your query, with their follower counts. On Instagram it is the profiles a Google search from the market finds, each read from its About this account panel and kept only when the creator declares that country, with followers and bio. Each creator then carries country ({ value, source }, where source is post_region on TikTok and declared_country on Instagram) and evidence (up to 3 posts or the profile text that found it, with links), and data.country counts per source what was kept and what was dropped as another country, off topic or with no country declared. min_followers, verified_only, sort and brief work as they do without it. Flat 10 credits with a coverage-based partial refund; with country, the searches it runs are billed on top at their own price.
75개 플랫폼을 하나의 API로 제공합니다
Creators API로 무엇을 할 수 있을까요
Creators 엔드포인트가 통합 스키마와 계산 필드를 담은 Universal Search 데이터를 한 번의 요청으로 보내드려요. 스크래핑 인프라를 직접 만들거나 유지할 필요가 없어요.
요청 예시
# GET /v1/search/creators: Metered: holds 10 credits per call up front and refunds what the call does not use. Cache hits are free and failed calls are refunded.
# Check the price first for 0 credits: add dry_run=1 to the query. Nothing is fetched or charged.
# --max-time 19: this endpoint's measured p99 latency x 1.5.
# --retry 3: retries timeouts, 429 and 5xx, honoring Retry-After.
# -o response.json keeps only the final attempt's body.
# One Idempotency-Key per request, reused on every retry, so a retried call is never charged twice.
IDEMPOTENCY_KEY=$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n')
curl -sS --max-time 19 --retry 3 -o response.json \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
"https://www.socialcrawl.dev/v1/search/creators?query=skincare+routine&sources=tiktok%2Cinstagram&min_followers=50000&verified_only=false&sort=relevance&country=CL" && cat response.json# GET /v1/search/creators: Metered: holds 10 credits per call up front and refunds what the call does not use. Cache hits are free and failed calls are refunded.
# Check the price first for 0 credits: add dry_run=1 to the query. Nothing is fetched or charged.
import os
import random
import time
import uuid
import requests
API_KEY = os.environ.get("SOCIALCRAWL_API_KEY", "YOUR_API_KEY")
TIMEOUT_S = 19 # this endpoint's measured p99 latency x 1.5.
MAX_RETRIES = 3
URL = "https://www.socialcrawl.dev/v1/search/creators"
def backoff(attempt):
# Exponential backoff with jitter: about 1 s, 2 s, then 4 s.
return 2 ** attempt * (0.5 + random.random() / 2)
def socialcrawl(params):
# One Idempotency-Key per request, reused on every retry, so a retried call is never charged twice.
idempotency_key = str(uuid.uuid4())
for attempt in range(MAX_RETRIES + 1):
try:
res = requests.get(
URL,
params=params,
headers={"x-api-key": API_KEY, "Idempotency-Key": idempotency_key},
timeout=TIMEOUT_S,
)
body = res.json()
except (requests.RequestException, ValueError):
# A timeout, a dropped connection or a non-JSON gateway page: retry with the same key.
if attempt == MAX_RETRIES:
raise
time.sleep(backoff(attempt))
continue
if body["success"]:
return body
error = body["error"]
# Branch on error["type"], never on the message text.
if error["type"] == "RESOURCE_NOT_FOUND":
return None # refunded: nothing to read
retry_after = res.headers.get("Retry-After")
# SERVICE_UNAVAILABLE without Retry-After is a withdrawn endpoint: permanent.
permanent = error["type"] == "SERVICE_UNAVAILABLE" and retry_after is None
if not error.get("retryable") or permanent or attempt == MAX_RETRIES:
raise RuntimeError(f"{error['type']}: {error['message']} (request_id {body['request_id']})")
# Retry-After (seconds) wins; otherwise back off.
time.sleep(float(retry_after) if retry_after else backoff(attempt))
params = {
"query": "skincare routine",
"sources": "tiktok,instagram",
"min_followers": "50000",
"verified_only": "false",
"sort": "relevance",
"country": "CL",
}
body = socialcrawl(params)
if body is not None:
print(body["data"])// GET /v1/search/creators: Metered: holds 10 credits per call up front and refunds what the call does not use. Cache hits are free and failed calls are refunded.
// Check the price first for 0 credits: add dry_run=1 to the query. Nothing is fetched or charged.
const API_KEY = process.env.SOCIALCRAWL_API_KEY ?? "YOUR_API_KEY";
const TIMEOUT_MS = 19_000; // this endpoint's measured p99 latency x 1.5.
const MAX_RETRIES = 3;
type Page = { next_cursor: string | null; has_more: boolean };
type SocialCrawlResponse =
| { success: true; data: any; pagination?: Page; credits_used: number; request_id: string }
| { success: false; error: { type: string; message: string; retryable: boolean }; request_id: string };
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
// Exponential backoff with jitter: about 1 s, 2 s, then 4 s.
const backoffMs = (attempt: number) => 2 ** attempt * 1000 * (0.5 + Math.random() / 2);
async function socialcrawl(url: URL) {
// One Idempotency-Key per request, reused on every retry, so a retried call is never charged twice.
const idempotencyKey = crypto.randomUUID();
for (let attempt = 0; ; attempt++) {
let res: Response;
let body: SocialCrawlResponse;
try {
res = await fetch(url, {
headers: {
"x-api-key": API_KEY,
"Idempotency-Key": idempotencyKey,
},
signal: AbortSignal.timeout(TIMEOUT_MS),
});
body = (await res.json()) as SocialCrawlResponse;
} catch (error) {
// A timeout, a dropped connection or a non-JSON gateway page: retry with the same key.
if (attempt >= MAX_RETRIES) throw error;
await sleep(backoffMs(attempt));
continue;
}
if (body.success) return body;
// Branch on error.type, never on the message text.
if (body.error.type === "RESOURCE_NOT_FOUND") return null; // refunded: nothing to read
const retryAfter = res.headers.get("Retry-After");
// SERVICE_UNAVAILABLE without Retry-After is a withdrawn endpoint: permanent.
const permanent = body.error.type === "SERVICE_UNAVAILABLE" && retryAfter === null;
if (!body.error.retryable || permanent || attempt >= MAX_RETRIES) {
throw new Error(`${body.error.type}: ${body.error.message} (request_id ${body.request_id})`);
}
// Retry-After (seconds) wins; otherwise back off.
await sleep(retryAfter ? Number(retryAfter) * 1000 : backoffMs(attempt));
}
}
const url = new URL("https://www.socialcrawl.dev/v1/search/creators");
url.searchParams.set("query", "skincare routine");
url.searchParams.set("sources", "tiktok,instagram");
url.searchParams.set("min_followers", "50000");
url.searchParams.set("verified_only", "false");
url.searchParams.set("sort", "relevance");
url.searchParams.set("country", "CL");
const body = await socialcrawl(url);
if (body) console.log(body.data);함께 보내면 좋은 파라미터
country=CL지정한 국가의 결과만 반환합니다.
파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
| query | 예 | Niche or topic (2-256 chars), forwarded to every profile search. |
| sources | 아니오 | Optional CSV allowlist of creator sources (tiktok, threads, instagram, youtube, twitter, facebook). Mutually exclusive with exclude. Omit to keep the default TikTok + Threads + Instagram walk. With country, only tiktok and instagram (the default), and any other source is a free 400. |
| exclude | 아니오 | Optional CSV blocklist of creator sources. Mutually exclusive with sources. |
| min_followers | 아니오 | Drop fused creators whose follower count is below this integer floor. |
| verified_only | 아니오 | When true, keep only verified creators after fusion. |
| sort | 아니오 | Which axis dominates rank: relevance (default), followers, or verification. (relevance | followers | verification) |
| brief | 아니오 | Optional. What you want to find, in your own words (3-300 chars), for example brief=Korean creators who review skincare products. The first 40 creators are judged from their name, handle and bio: does the account post about your brief (fits_brief, 0 to 1), and what kind of account is it (individual_creator, brand_or_business, media_or_publisher, fan_or_repost_page, cannot_tell; null when unsure). With sort=relevance (the default) they are re-ranked so creators who fit and are individual people lead; other sorts keep their order and only gain the labels. These are signals to review, not a finding. Adds 2 credits. |
| relevance | 아니오 | Optional, only with brief. score (default) ranks and labels; filter also drops judged creators that do not fit the brief and lists them in data.brief.dropped_ids. A creator that could not be judged is never dropped. (score | filter) |
| judgments | 아니오 | Optional. on (default) or off. On, the first 40 creators also carry account ({ account_kind: individual_creator, brand_or_business, media_or_publisher, fan_or_repost_page, cannot_tell or null when unsure, account_kind_confidence, named_person }), judged from their name, handle and bio, and data.account_kinds reports how many were judged. The order is unchanged and it is free. off returns the response without it. (on | off) |
| country | 아니오 | Optional. Two-letter market code (CL, AR, MX, CO, PE, EC, UY, ES, BR) to find the creators who post about your query in that market, instead of searching account names. Runs on TikTok and Instagram: the market's name is added to your query, TikTok creators are kept when the video's own region is the market and its text is about your query, and Instagram creators when they declare that country on their About this account panel. Each creator carries country and evidence, and data.country reports the query sent and what was kept and dropped per source. The searches and lookups it runs are billed on top at their own price, at most 12 credits. Any other code is a free 400. (CL | AR | MX | CO | PE | EC | UY | ES | BR) |
Universal Search Creators API는 무엇을 돌려주나요
모든 응답은 하나의 통합 스키마를 따라요. 크레딧을 쓰기 전에 어떤 필드가 돌아오는지, 실제 응답 본문 그대로 확인해 보세요.
응답 예시 보기
{
"success": true,
"platform": "search",
"endpoint": "/v1/search/creators",
"data": {
"creators": [
{
"author": {
"id": "user_058794",
"username": "user_1cb194",
"display_name": "user_a15759",
"bio": null,
"followers": 6045690,
"verified": false,
"avatar_url": "https://example.com/avatars/user_805cd1.png",
"url": "https://example.com/user_d7235c"
},
"sources": [
"tiktok"
],
"relevance": 0.45,
"follower_rank": 1,
"verified": false,
"rrf_score": 0.017897727272727273,
"account": {
"account_kind": "individual_creator",
"account_kind_confidence": 1,
"named_person": 0.87
}
}
],
"creators_by_source": {
"tiktok": [
{
"id": "user_b598dc",
"username": "user_4d9b4a",
"display_name": "user_67c672",
"bio": null,
"followers": 36,
"verified": false,
"avatar_url": "https://example.com/avatars/user_ea00c5.png",
"url": "https://example.com/user_c06400"
},
{
"id": "user_a8ec20",
"username": "user_7b906f",
"display_name": "user_3af5a8",
"bio": null,
"followers": 5085,
"verified": false,
"avatar_url": "https://example.com/avatars/user_676794.png",
"url": "https://example.com/user_e80546"
}
],
"threads": [],
"instagram": [
{
"id": "user_d64a0b",
"username": "user_c1e003",
"display_name": "user_2c8d0f",
"bio": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).",
"followers": 22456,
"verified": false,
"avatar_url": "https://example.com/avatars/user_99e358.png",
"url": "https://example.com/user_60d233"
},
{
"id": "user_9a0493",
"username": "user_d61117",
"display_name": "user_c043e7",
"bio": "Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted). Sample comment text (redacted).",
"followers": 28396,
"verified": false,
"avatar_url": "https://example.com/avatars/user_88de7a.png",
"url": "https://example.com/user_995add"
}
],
"youtube": [],
"twitter": [],
"facebook": []
},
"computed": {
"platform_spread": {
"tiktok": 30,
"instagram": 44
},
"verified_share": 0,
"follower_distribution": {
"p50": 6045690,
"p90": 6045690
}
},
"legs": [
{
"endpoint": "/v1/tiktok/search/users",
"status": 200,
"credits_used": 1,
"latency_ms": 1941,
"error": null
},
{
"endpoint": "/v1/instagram/search/profiles",
"status": 200,
"credits_used": 1,
"latency_ms": 7963,
"error": null
}
],
"sources_called": [
"tiktok",
"instagram"
],
"sources_succeeded": [
"tiktok",
"instagram"
],
"coverage": 1,
"partial_failure": false,
"methodology_version": "search-creators/1.0",
"account_kinds": {
"methodology_version": "creators-account-kind/1",
"status": "complete",
"judged": 1,
"unjudged": 0
}
},
"credits_used": 10,
"request_id": "req_example000000",
"cached": false,
"credits_remaining": 9999,
"source": "captured",
"captured_at": "2026-10-02T12:48:35.176Z",
"redacted": true
}통합 응답 구조를 보여 주는 실제 샘플이에요. 필드 값은 조회한 대상에 따라 달라져요.
Universal Search Creators API는 어떻게 동작하나요
API 키와 함께 GET 요청을 보내면, 통합 스키마와 계산 필드를 담은 깔끔한 JSON이 돌아와요.
메서드
GET
응답 형식
JSON
소셜 미디어 데이터를 몇 초 만에 수집하는 방법
개발자를 위한 가장 빠른 소셜 미디어 스크래핑 API. 월간 활성 사용자 100억 명 이상을 포괄하는 75개 플랫폼에서 프로필, 게시물, 댓글, 분석 데이터를 수집하세요.
모든 플랫폼을 하나의 스키마로
동일한 응답 구조로 75개 플랫폼을 조회하세요. 연동은 한 번이면 충분합니다.
단순 수집을 넘어 계산된 필드 제공
엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때, 정규화된 레코드에 engagement_rate, estimated_reach, content_category, language를 함께 담아 바로 활용할 수 있습니다.
코드 한 줄 쓰기 전에, 데이터부터
Visual Data Explorer에 URL만 붙여넣으면 결과 카드와 정형화된 테이블, CSV 내보내기를 바로 사용할 수 있습니다.
import requests
response = requests.get(
'https://www.socialcrawl.dev/v1/tiktok/profile',
params={'handle': 'charlidamelio'},
headers={'x-api-key': 'sc_YOUR_API_KEY'}
)
data = response.json(){
"success": true,
"platform": "tiktok",
"data": {
"author": {
"username": "charlidamelio",
"followers": 152400000
},
"engagement": {
"likes": 12400000000,
"engagement_rate": 0.087
},
"metadata": {
"language": "en",
"content_category": "lifestyle"
}
}
}자주 묻는 질문
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기인플루언서는 API로 어떻게 검색하나요?
크리에이터 순위는 어떤 기준으로 정하나요?
팔로워 수나 인증 여부로 거를 수 있나요?
키워드가 아니라 설명으로 크리에이터를 찾을 수 있나요?
특정 국가의 크리에이터만 찾을 수 있나요?
인플루언서 검색 API는 크레딧이 얼마나 드나요?
AI에게 SocialCrawl을 물어보세요
Universal Search Creators 데이터, 가져올 준비 되셨어요?
API 키 받고 60초 안에 Universal Search 데이터를 받아 가세요.
