Twitter User Search
X에서 관련성 높은 크리에이터, 기업, 전문가 프로필을 찾으려면 계정 핸들과 소개글을 대상으로 한 정교한 키워드 매칭이 필요합니다. 정규화된 프로필 결과로 사용자 이름, 표시 이름, 소개글, 위치 정보, 팔로워 수, 인증 배지를 받을 수 있습니다.
Twitter User Search API 주요 기능
- 키워드 기반 계정 매칭원하는 검색어를 제출하면 이름, 사용자 이름, 계정 소개글에서 관련 공개 프로필을 찾아냅니다.
- 정규화된 프로필 속성사용자 ID, 핸들, 표시 이름, 아바타, 배너, 소개글 텍스트가 담긴 일관된 객체를 받습니다.
- 오디언스 수치반환된 계정마다 현재의 팔로워, 팔로잉, 전체 게시물, 미디어, 좋아요 수를 가져옵니다.
- 인증 및 상태 플래그파란색 인증 배지, 자동화 봇 플래그, 비공개 계정 여부, 위치 문자열을 확인할 수 있습니다.
Twitter User Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 일치하는 공개 X 사용자 프로필을 찾기 위한 검색 키워드입니다. |
results_limit | 선택 | 반환할 최대 사용자 프로필 수입니다. 20부터 2,000 사이의 20의 배수여야 하며 기본값은 20입니다. |
Twitter User Search API 사용 방법
키워드 검색어를 비동기 작업으로 제출한 뒤, 정규화된 사용자 프로필을 페이지 단위로 읽습니다.
- query에 검색어를 지정하고, results_limit은 20의 배수(최대 2,000)로 설정합니다.
- SocQ API 키와 함께 /v1/x/search-users로 POST 요청을 보냅니다.
- 작업 상태가 succeeded가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items에서 정규화된 계정 레코드를 가져옵니다.
curl -X POST "https://api.socq.ai/v1/x/search-users" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"OpenAI","results_limit":20}'
# Poll GET /v1/tasks/{task_id}, then fetch data.results.items.Twitter User Search API 추천 활용 사례
- 인플루언서·분야 전문가 발굴: 업계 용어로 검색해 영향력 있는 분야 전문가, 기자, 오피니언 리더를 찾습니다.
- 브랜드 계정 점검: 플랫폼 전반에서 브랜드 핸들, 지역별 현지 법인 계정, 비공식 팬 계정을 찾아냅니다.
- 아웃리치 대상 목록 생성: 공개 소개글의 키워드로 걸러 낸 관련 전문가들의 잠재 고객 목록을 구축합니다.
Twitter User Search API 활용 팁
- 이 엔드포인트는 계정을 찾을 때 사용하고, 개별 게시물을 찾을 때는 X Search를 사용하세요.
- results_limit은 상위 제공처의 페이지네이션 묶음에 맞추기 위해 20의 배수(예: 20, 40, 100)여야 합니다.
- is_verified와 verified_type 속성을 확인하면 계정이 공식적으로 인증되었는지 알 수 있습니다.
- 발견한 사용자 이름을 X User Posts나 X Following List에 전달하면 해당 계정의 오디언스 관계를 더 깊이 살펴볼 수 있습니다.
관련 API
Twitter User Search API 외에 X의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Twitter Profile Scraper API — 사용자 이름으로 공개 계정 정보, 소개글, 프로필 이미지, 커버 이미지, 계정 상태, 공개된 오디언스 통계를 가져옵니다.
- Twitter User Tweets Scraper API — 사용자 이름으로 최근 공개 게시물, 작성자, 미디어, 해시태그, 멘션, 참여도를 수집하며 답글은 제외합니다.
- Twitter Search API — 검색식으로 공개 게시물을 찾으며, 최신순 또는 인기순 정렬과 결과 수 제한을 지정할 수 있습니다.
- X Followers List API — X 사용자 이름 하나 이상에 대해 공개 팔로워 계정 정보와 공개된 프로필 지표를 수집합니다.
- X Trends API — 알고 있는 숫자형 WOEID의 현재 공개 X 트렌드 스냅샷을 수집하며, 출처 순위, 검색어, 설명, 위치 맥락을 포함합니다.
- X Communities Search API — 키워드로 커뮤니티를 찾고, 멤버 수와 멤버·게시물 엔드포인트에 바로 쓸 수 있는 링크를 반환합니다.
- Twitter Tweet Scraper API
- X Following List API
- X Post Quotes API
- X Post Replies API
- X Post Retweeters API
- Twitter Mentions API
- X Community API
- X Community Posts API
- X Thread Context API
- X Account Location API
- X Verified Followers API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API