x/
search-users

키워드로 공개 X 사용자 계정을 검색하며, 정규화된 계정 정보, 소개글, 인증 상태, 오디언스 수치를 반환합니다.

Twitter User Search API

사용자 검색
계정 탐색
정규화된 프로필
결과당 0.6 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

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

키워드 검색어를 비동기 작업으로 제출한 뒤, 정규화된 사용자 프로필을 페이지 단위로 읽습니다.

  1. query에 검색어를 지정하고, results_limit은 20의 배수(최대 2,000)로 설정합니다.
  2. SocQ API 키와 함께 /v1/x/search-users로 POST 요청을 보냅니다.
  3. 작업 상태가 succeeded가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. 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에 전달하면 해당 계정의 오디언스 관계를 더 깊이 살펴볼 수 있습니다.

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 — 키워드로 커뮤니티를 찾고, 멤버 수와 멤버·게시물 엔드포인트에 바로 쓸 수 있는 링크를 반환합니다.

다른 플랫폼 둘러보기

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

Twitter User Search API — 자주 묻는 질문

Twitter User Search API는 텍스트 검색어로 X 전반의 공개 사용자 계정과 크리에이터 프로필을 검색합니다. 팔로워 수, 소개글, 인증 배지, 아바타 URL이 담긴 정규화된 프로필 레코드를 반환합니다.

X Search 엔드포인트는 키워드와 일치하는 공개 게시물을 검색하고, Twitter User Search는 사용자 계정과 채널 프로필을 전문적으로 검색합니다.

상위 제공처가 사용자 검색 결과를 20개씩 고정된 페이지로 전달하므로, 요청 상한도 딱 떨어지는 20의 배수여야 합니다.