Threads User Search
Threads 사용자 검색은 입력한 이름이나 핸들에 대해 앱이 추천하는 계정 목록으로, 각 계정은 사용자 이름, 표시 이름, 프로필 링크, 아바타, 인증 배지로 식별됩니다. 이 식별 정보로 실제 인물이나 브랜드를 이름이 비슷한 계정과 구분하고, 단순한 이름 목록을 확인된 Threads 프로필로 바꿀 수 있습니다.
Threads User Search API 주요 기능
- 이름과 핸들 모두로 검색query 값에는 표시 이름이나 사용자 이름을 넣을 수 있고, 응답에는 Threads가 추천하는 계정이 보통 최대 10개까지 담깁니다.
- 바로 쓸 수 있는 식별 필드일치 계정마다 username, name, url 값이 반환되며, url 값은 다른 Threads 엔드포인트가 입력으로 받는 /@username 형식의 프로필 링크입니다.
- 동명 계정 구분을 돕는 배지와 아바타같은 이름의 계정이 여럿일 때 is_verified와 avatar_url 값으로 진짜 계정을 고를 수 있습니다.
Threads User Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 인물이나 브랜드의 이름, 또는 shams 같은 Threads 사용자 이름입니다. |
Threads User Search API 사용 방법
이름을 검색하고 추천된 계정을 읽습니다.
- {"query": "shams"}을 /v1/threads/search-users로 POST합니다.
- 반환된 task_id 값으로 status 값이 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링합니다.
- results.items에서 일치 계정을 읽고, has_more 값이 true일 때마다 results.next_cursor를 따라갑니다.
curl -X POST "https://api.socq.ai/v1/threads/search-users" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"shams"}'
# 0.6 credits for each account returned.Threads User Search API 추천 활용 사례
- 콘텐츠 수집 전 핸들 확인: username, 표시 이름, is_verified 값으로 맞는 계정을 확인한 뒤 그 url 값으로 해당 계정의 게시물, 답글, 리포스트를 가져옵니다.
- 이름 목록을 Threads 프로필로 변환: 인플루언서 목록이나 기자 목록의 이름을 하나씩 검색하고 인증된 계정의 url 값을 남겨 Threads 프로필 링크 열을 만듭니다.
- 사칭 의심 계정 발견: 브랜드나 공인을 검색한 뒤 이름과 아바타가 거의 같은 미인증 계정을 검토해 사칭 계정이나 팬 페이지 가능성을 확인합니다.
Threads User Search API 활용 팁
- 원하는 계정이 첫 결과에 없으면 전체 이름과 예상되는 핸들을 모두 시도해 보세요. query 값은 둘 중 어느 쪽과도 일치합니다.
- 흔한 이름은 비슷한 계정이 여러 개 나오므로 첫 행을 그대로 쓰지 말고 username과 is_verified 값을 함께 보고 고르세요.
- 고른 url 값은 같은 형식의 프로필 링크를 받는 Threads User Posts, User Replies, User Reposts API에 바로 넘길 수 있습니다.
관련 API
Threads User Search API 외에 Threads의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Threads Posts API — 지원되는 Threads 게시물 URL에서 공개 게시물 텍스트, 작성자 맥락, 미디어, 타임스탬프, 공개된 참여도를 수집합니다.
- Threads Profiles API — 지원되는 Threads 프로필 URL에서 공개 프로필 정보, 소개글, 이미지, 웹사이트, 공개된 계정 수치, 수집 맥락을 수집합니다.
- Threads User Posts API — Threads 프로필 URL에서 공개 게시물을 찾으며, 프로필별 결과 수 제한과 정규화된 콘텐츠, 작성자, 미디어, 타임스탬프, 공개된 참여도, 출처 맥락을 포함합니다.
- Threads Post Replies API — 게시물 URL로 Threads 게시물 아래의 답글을 수집하며 답글 텍스트, 작성자, 좋아요·답글 수, 미디어, 답글 대상 게시물 ID를 포함합니다.
- Threads Search API — 키워드나 해시태그로 Threads 상위 게시물을 검색하며 텍스트, 작성자, 좋아요, 답글, 리포스트, 미디어, 게시 시각을 포함합니다.
- Threads User Replies API — Threads 프로필 URL로 계정이 올린 최신 공개 답글을 수집하며 답글 텍스트, 참여 지표, 미디어, 링크를 포함합니다.