tiktok/
followers-list

하나 이상의 사용자 이름에 대해 공개된 TikTok 팔로워 목록에서 정규화된 프로필을 수집하고, 출처 정보, 프로필 링크, 제공되는 공개 수치를 함께 반환합니다.

TikTok Followers List API

팔로워 프로필
오디언스 샘플링
공개 목록 조사
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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 사용 방법

알고 있는 공개 핸들을 제출하고 비동기 작업이 끝날 때까지 기다린 뒤, 저장된 프로필 레코드를 페이지 단위로 읽습니다.

  1. 공백을 제거하고, 직접 중복을 정리하기 위해 앞에 붙은 @는 지우고, 공개 TikTok 사용자 이름을 고릅니다.
  2. usernames와 사용자 이름별 results_limit(20~2,000)을 /v1/tiktok/followers-list로 POST합니다.
  3. task_id를 저장하고 /v1/tasks/{task_id}를 폴링합니다. queued, running, retrying은 정상적인 중간 상태입니다.
  4. 성공하면 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 true

TikTok 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로 취급하세요.

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 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

TikTok Followers List API — 자주 묻는 질문

TikTok Followers List API는 하나 이상의 TikTok 사용자 이름에서 공개된 팔로워 프로필을 수집하는 프로그래밍 인터페이스입니다. 정규화된 식별 정보, 소개글, 프로필 링크, 제공되는 공개 수치를 반환합니다.

공개 핸들을 담은 비어 있지 않은 usernames 배열을 제출하며, 앞에 @가 붙어도 됩니다. 선택 값인 results_limit도 지정할 수 있습니다. 대상의 숫자 ID, 프로필 URL, 수집 커서는 허용되지 않습니다.

20~2,000 사이의 정수이고 기본값은 100이며, 사용자 이름마다 따로 적용됩니다. 요청하는 수집량의 상한일 뿐, 그만큼의 공개 레코드가 있다는 보장은 아닙니다.

정규화된 레코드에는 ID, 사용자 이름, 표시 이름, 소개글 텍스트, 아바타 참조, 프로필 URL, null일 수 있는 공개 수치, collected_at, extra.input_username이 들어 있습니다. created_at은 현재 null입니다.

TikTok 피드의 페이지네이션은 내부적으로 처리되며 제출 매개변수가 아닙니다. 성공 후 반환되는 next_cursor는 /v1/tasks/{task_id}에 저장된 결과의 다음 페이지를 불러오는 용도로만 쓰입니다.

확실하게 알 수는 없습니다. 저장된 결과는 작업 안에서 팔로워 ID 또는 프로필 URL을 기준으로 중복이 제거되므로, 반복된 팔로워는 하나의 input_username과 함께 한 번만 남고 전체 출처 관계가 모두 보존되지는 않습니다.

저장된 정규화 결과 1건당 0.5 크레딧이 차감되며 기본 요금은 없습니다. 처음 예상 금액은 results_limit에 제출한 사용자 이름 수를 곱해 계산하고, 사용하지 않은 선차감 크레딧은 작업이 끝난 뒤 환불됩니다.