x/
followers-list

하나 이상의 X 사용자 이름에 대한 공개 팔로워 계정을 수집하며, 정규화된 계정 정보, 공개된 프로필 수치, 비동기 작업, 커서 기반 조회를 지원합니다.

X Followers List API

팔로워 계정
프로필 수치
일괄 수집
결과당 0.5 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

X Followers List

X 팔로워 목록은 제출한 사용자 이름을 수집 시점에 팔로우하고 있는 사람들의 공개 계정 레코드 모음입니다. 오디언스 조사와 목록 정보 보강에 활용할 수 있으며, 공개 여부, 제공처 페이지네이션, 작업 단위 중복 제거의 영향을 받습니다.

X Followers List API 주요 기능

  • 여러 계정의 팔로워 수집공개 X 사용자 이름을 하나 이상 한 작업에 제출할 수 있으며, 맨 앞의 @는 있어도 없어도 됩니다.
  • 사용자 이름별 결과 수 제어사용자 이름마다 팔로워 레코드를 200개 단위로 200~2,000개 요청할 수 있으며, 기본값은 200입니다.
  • 정규화된 공개 계정 레코드계정 ID, 정식 프로필 URL, 작성자 정보, 공개된 프로필 수치, 정규화된 타임스탬프를 공개 작업 결과로 받습니다.
  • 비동기 전달 방식수집이 끝날 때까지 불투명 커서로 작업 결과를 폴링한 뒤, 사용 가능한 모든 결과 페이지를 이어서 읽습니다.

X Followers List API 매개변수

매개변수필수설명
usernames필수공개 X 사용자 이름의 목록으로, 필수 값입니다. 맨 앞의 @는 있어도 없어도 되며, 수집 전에 공백이 제거되고 대소문자 구분 없이 중복된 사용자 이름이 삭제됩니다.
results_limit선택사용자 이름별로 수집할 최대 결과 수입니다. 기본값은 200이며 200부터 2,000까지 200의 배수를 받습니다.

X Followers List API 사용 방법

팔로워 수집 작업을 시작하고 완료될 때까지 기다린 뒤, 저장된 공개 계정 레코드를 페이지 단위로 읽습니다.

  1. 공개 X 사용자 이름을 하나 이상 준비합니다. 맨 앞의 @는 선택 사항입니다.
  2. usernames와 유효한 results_limit을 /v1/x/followers-list로 POST하고, 반환된 task_id를 저장합니다.
  3. 작업이 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. 성공하면 data.results.items를 읽고, has_more가 true인 동안 next_cursor를 작업 엔드포인트에 다시 전달합니다.
curl -X POST "https://api.socq.ai/v1/x/followers-list" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["@X"],"results_limit":200}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

X Followers List API 추천 활용 사례

  • 오디언스 조사용 표본 구축: 선택한 X 프로필의 공개 팔로워 계정을 수집해, 반환된 표본 전체에서 공개된 계정 규모를 분석합니다.
  • 알고 있는 계정 디렉터리 정보 보강: 정식 X 프로필 URL, 표시 이름, 계정 ID, 공개된 수치를 후속 계정 레코드에 추가합니다.
  • 반복 가능한 팔로워 스냅샷 생성: 같은 범위의 수집을 시간을 두고 반복 실행하고 작업 타임스탬프를 보관해, 저장된 공개 계정 집합을 서로 비교합니다.

X Followers List API 활용 팁

  • 임시 크레딧 예상치는 제출한 배열 길이를 기준으로 계산하는 반면 수집 단계에서는 중복 핸들이 정규화되므로, 제출 전에 사용자 이름의 중복을 제거하세요.
  • results_limit은 사용자 이름별 상한일 뿐이며, 모든 계정에서 요청한 수만큼의 공개 레코드가 반환된다는 보장이 아닙니다.
  • 각 결과의 id를 안정적인 키로 사용하세요. 제출한 여러 사용자 이름에서 같은 팔로워가 발견되어도 한 작업 안에서는 한 번만 저장됩니다.
  • 제공처 페이지네이션과 결과 조회는 분리해서 생각하세요. 공개되는 것은 /v1/tasks/{task_id}가 반환하는 불투명한 next_cursor뿐입니다.
  • 사용할 수 없는 계정, 접근 제한, 원본 소진으로 수집 결과가 짧아질 수 있으므로, 빈 결과나 일부 결과 때문에 워크플로가 실패하지 않도록 처리하세요.

X Followers List API 외에 X의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Twitter Profile Scraper API — 사용자 이름으로 공개 계정 정보, 소개글, 프로필 이미지, 커버 이미지, 계정 상태, 공개된 오디언스 통계를 가져옵니다.
  • X Following List API — 공개 X 계정이 팔로우하는 프로필을 수집하며, 계정 정보, 소개글, 계정 신호, 공개된 카운터, 출처 사용자 이름을 포함합니다.
  • X Post Retweeters API — 알고 있는 X 또는 Twitter 게시물 URL을 리포스트한 계정의 정규화된 공개 프로필을 작업 단위로 중복 없이 수집합니다.
  • X Community API — 커뮤니티 링크에서 소개, 멤버 수, 규칙, 가입 정책을 가져옵니다.
  • X Verified Followers API — 프로필을 팔로우하는 인증 계정을 사용자 이름, 표시 이름, 프로필 사진, 가입일과 함께 수집합니다.
  • Twitter Follow Checker API — 한 계정이 다른 계정들을 팔로우하는지, 상대가 맞팔로우하는지 확인합니다.

다른 플랫폼 둘러보기

X 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

X Followers List API — 자주 묻는 질문

X Followers List API는 제출한 하나 이상의 X 사용자 이름을 팔로우하는 사람들의 공개 계정 레코드를 수집하는 프로그래밍 인터페이스입니다.

비어 있지 않은 usernames 배열을 전달합니다. 각 값의 맨 앞 @는 있어도 없어도 되며, 제공처 수집 전에 앞뒤 공백이 제거되고 대소문자 구분 없이 중복된 핸들이 삭제됩니다.

이 값은 사용자 이름마다 따로 적용되며 기본값은 200이고, 200부터 2,000 사이의 200의 배수여야 합니다. 상한이므로 공개 여부와 페이지네이션에 따라 더 적은 결과가 나올 수 있습니다.

현재 작업 시리얼라이저는 계정 ID, 정식 프로필 URL, 작성자 ID, 사용자 이름과 이름, 공개된 프로필 수치, 확인 가능한 경우 정규화된 계정 생성 시각, 저장된 레코드의 생성 시각을 반환합니다.

제공처에서 반복된 행은 계정 ID 기준으로 중복이 제거되며, 제출한 사용자 이름을 둘 이상 팔로우하는 계정이라도 작업 전체에서 한 번만 저장됩니다.

중복 없이 저장된 결과 하나당 0.5 SocQ 크레딧이 차감됩니다. 작업을 시작할 때 results_limit에 제출한 사용자 이름 수를 곱한 만큼 먼저 차감하고, 정산이 성공하면 사용하지 않은 크레딧을 환불합니다. 결과가 없으면 0 크레딧입니다.