TikTok Followers List
공개된 TikTok 팔로워 목록에서는 계정 식별 정보, 소개글, 프로필 링크, 제공되는 오디언스·활동 수치를 확인할 수 있습니다. 이러한 레코드는 오디언스 샘플링, 크리에이터 탐색, 정보 보강 대기열, 공개 목록의 반복 조사에 활용할 수 있습니다.
TikTok Followers List API 주요 기능
- 여러 계정 일괄 수집공개 사용자 이름 하나 이상의 팔로워를 수집하며, results_limit은 제출한 계정마다 따로 적용됩니다.
- 범위가 제한된 목록 순회지원되는 팔로워 페이지를 내부적으로 순회하다가 계정별 한도에 도달하거나, 다음 페이지를 사용할 수 없거나, 수집 상한에 이르면 멈춥니다.
- 정규화된 프로필 레코드팔로워 ID, 사용자 이름, 표시 이름, 소개글, 아바타 참조, 프로필 URL, 지원되는 공개 수치를 일관된 프로필 구조로 반환합니다.
- 출처 정보 보존남겨진 팔로워 레코드마다 정규화한 제출 핸들을 extra.input_username에 보관합니다.
- 작업 단위 중복 제거결과를 저장하고 페이지로 나누기 전에, 정규화된 ID 또는 프로필 URL을 기준으로 작업 전체에서 반복되는 팔로워를 제거합니다.
TikTok Followers List API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
usernames | 필수 | 공개 TikTok 사용자 이름의 목록으로, 비어 있지 않아야 하는 필수 값입니다. 앞의 @는 있어도 없어도 되며, 숫자형 계정 ID, 프로필 URL, 커서 값은 허용되지 않습니다. |
results_limit | 선택 | 20~2,000 사이의 정수로, 선택 값이며 기본값은 100입니다. 제출한 사용자 이름마다 따로 적용되며, 상한일 뿐 전체 수집을 보장하는 값은 아닙니다. |
TikTok Followers List API 사용 방법
알고 있는 공개 핸들을 제출하고 비동기 작업이 끝날 때까지 기다린 뒤, 저장된 프로필 레코드를 페이지 단위로 읽습니다.
- 공백을 제거하고, 직접 중복을 정리하기 위해 앞에 붙은 @는 지우고, 공개 TikTok 사용자 이름을 고릅니다.
- usernames와 사용자 이름별 results_limit(20~2,000)을 /v1/tiktok/followers-list로 POST합니다.
- task_id를 저장하고 /v1/tasks/{task_id}를 폴링합니다. queued, running, retrying은 정상적인 중간 상태입니다.
- 성공하면 data.results.items를 읽고, has_more가 true인 동안 next_cursor를 같은 작업 엔드포인트에 전달합니다.
curl -X POST "https://api.socq.ai/v1/tiktok/followers-list" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["@loganpaul"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueTikTok Followers List API 추천 활용 사례
- 공개 오디언스 샘플링: 공개된 팔로워 프로필로 범위가 제한된 표본을 만들어 정성적인 오디언스 검토에 활용합니다.
- 크리에이터 탐색 대기열: 수동 검토나 이후 TikTok Profiles 정보 보강 작업의 시드로 쓸 수 있는 팔로워 사용자 이름과 프로필 링크를 수집합니다.
- 반복 목록 조사: 같은 공개 계정에서 시각이 기록된 표본을 저장해 수집할 때마다 달라지는 계정 구성을 관찰합니다.
- 프로필 디렉터리 입력 데이터: 공개 팔로워 목록의 항목을 일관된 식별 정보, 소개글, 아바타, 수치 필드로 변환해 내부 디렉터리에 활용합니다.
TikTok Followers List API 활용 팁
- 클라이언트에서 중복을 제거하기 전에 대소문자를 통일하고 앞의 @를 제거하세요. 그렇지 않으면 @name과 name이 동일한 원본 조회를 유발할 수 있습니다.
- results_limit은 사용자 이름별 상한으로 보세요. 기본값 100으로 사용자 이름 2개를 제출하면 예상 결과는 100건이 아니라 200건입니다.
- extra.input_username은 보관하되, 작업 단위 중복 제거 시 팔로워마다 출처 정보가 하나만 남으므로 이 엔드포인트를 정확한 공통 팔로워 분석에 쓰지 마세요.
- 반환된 계정을 TikTok 사용자 이름을 받는 엔드포인트에 넘길 때는 숫자 id가 아니라 팔로워의 username을 사용하세요.
- 새 수집 요청에 next_cursor를 제출하지 마세요. 같은 성공 작업에 이미 저장된 결과를 페이지로 넘기는 용도로만 쓰입니다.
- 원본의 팔로워 행에는 해당 필드가 항상 포함되지는 않으므로, metrics는 null일 수 있다고 보고 created_at은 null로 처리하세요.
- 비공개, 제한, 사용 불가 계정이나 규모가 매우 큰 계정은 레코드가 적게 나올 수 있으며, 아바타 참조는 만료될 수 있는 원본 URL로 취급하세요.
관련 API
TikTok Followers List API 외에 TikTok의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 계정 속성, 오디언스 수치를 가져옵니다.
- TikTok Following List API — TikTok 계정이 팔로우하는 공개 프로필을 수집하며, 정규화된 계정 정보, 소개글, 공개된 지표, 출처 계정 맥락을 포함합니다.
- TikTok User Videos API — 사용자 이름으로 공개 프로필 피드 동영상을 수집하며, 캡션, 크리에이터, 미디어, 타임스탬프, 참여도, 출처 계정 맥락을 포함합니다.
- TikTok Audience Demographics API — 사용자 이름으로 크리에이터의 팔로워가 어느 국가에 있는지 확인하며, 국가별 오디언스 비중을 포함합니다.
- TikTok Similar Accounts API — TikTok이 사용자 이름과 비슷하다고 추천하는 계정을 찾으며, 팔로워 수와 소개를 포함합니다.
- TikTok Live Ranking API — 일간 LIVE 크리에이터 순위를 순위, 선물 기반 점수, 팔로워 수와 함께 가져옵니다.
- TikTok Hashtags API
- TikTok Comments API
- TikTok Videos API
- TikTok Search API
- TikTok Comment Replies API
- TikTok Live Room Info API
- TikTok Trending Feed API
- TikTok Video Transcript API
- TikTok Search Users API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok Top Search API
- TikTok User Live API
- TikTok Reposts API
- TikTok Playlists API
- TikTok Hashtag Views API
- TikTok Sound Search API
- TikTok Live Search API
- TikTok Photo Search API
- TikTok Trending Searches API
- TikTok Creator Search Insights API
- TikTok Live Shopping API
- TikTok Fake Views Checker API
- TikTok Comment Keywords API