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 사용 방법
팔로워 수집 작업을 시작하고 완료될 때까지 기다린 뒤, 저장된 공개 계정 레코드를 페이지 단위로 읽습니다.
- 공개 X 사용자 이름을 하나 이상 준비합니다. 맨 앞의 @는 선택 사항입니다.
- usernames와 유효한 results_limit을 /v1/x/followers-list로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 성공하면 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 trueX Followers List API 추천 활용 사례
- 오디언스 조사용 표본 구축: 선택한 X 프로필의 공개 팔로워 계정을 수집해, 반환된 표본 전체에서 공개된 계정 규모를 분석합니다.
- 알고 있는 계정 디렉터리 정보 보강: 정식 X 프로필 URL, 표시 이름, 계정 ID, 공개된 수치를 후속 계정 레코드에 추가합니다.
- 반복 가능한 팔로워 스냅샷 생성: 같은 범위의 수집을 시간을 두고 반복 실행하고 작업 타임스탬프를 보관해, 저장된 공개 계정 집합을 서로 비교합니다.
X Followers List API 활용 팁
- 임시 크레딧 예상치는 제출한 배열 길이를 기준으로 계산하는 반면 수집 단계에서는 중복 핸들이 정규화되므로, 제출 전에 사용자 이름의 중복을 제거하세요.
- results_limit은 사용자 이름별 상한일 뿐이며, 모든 계정에서 요청한 수만큼의 공개 레코드가 반환된다는 보장이 아닙니다.
- 각 결과의 id를 안정적인 키로 사용하세요. 제출한 여러 사용자 이름에서 같은 팔로워가 발견되어도 한 작업 안에서는 한 번만 저장됩니다.
- 제공처 페이지네이션과 결과 조회는 분리해서 생각하세요. 공개되는 것은 /v1/tasks/{task_id}가 반환하는 불투명한 next_cursor뿐입니다.
- 사용할 수 없는 계정, 접근 제한, 원본 소진으로 수집 결과가 짧아질 수 있으므로, 빈 결과나 일부 결과 때문에 워크플로가 실패하지 않도록 처리하세요.
관련 API
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 — 한 계정이 다른 계정들을 팔로우하는지, 상대가 맞팔로우하는지 확인합니다.
- Twitter Tweet Scraper API
- Twitter User Tweets Scraper API
- Twitter Search API
- X Post Quotes API
- X Post Replies API
- X Trends API
- Twitter Mentions API
- Twitter User Search API
- X Community Posts API
- X Thread Context API
- X Account Location API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Communities Search API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Video Transcript API