Threads search_users API

REST 호출 한 번으로 Threads search_users 데이터를 조회 — 모든 플랫폼이 공유하는 안정적인 JSON 스키마로 정규화됩니다.

게시된 엔드포인트 1개
GET /v1/threads/search/users

계약 요약(영어): Search Threads users (capability threads.search_users)

정규화된 응답 엔터티: threads/search_users
capability: threads.search_users

모든 응답에는 신선도(cache / default / live)와 과금 메타데이터도 포함됩니다.

활용 사례

키워드로 {{platform}} 콘텐츠와 계정을 검색, 점수화에 바로 쓸 수 있는 정규화 결과를 반환합니다.
인기 주제와 핫 리스트를 추적해 떠오르는 대화를 조기에 포착.
검색·트렌드 쿼리에 알림을 설정해 변화를 실시간으로 인지.

응답 필드

Threads threads.search_users response (normalized envelope)

Response envelope of the /v1/threads threads.search_users capability. Cursor is opaque and platform-independent; page size follows the request's `limit` parameter (1..100, default 20).

필드	타입	필수	설명
data	profile[]	필수	—
next_cursor	string \| null	필수	Opaque pagination cursor; null when the list is exhausted.
query	string	선택	The echoed search query.
meta.request_id	string	필수	—
meta.freshness.mode	cache \| default \| live	필수	—
meta.freshness.age_seconds	integer \| null	선택	—
meta.freshness.source_layer	cache \| db \| upstream	필수	—
meta.freshness.stale	boolean	선택	—
meta.billing.cache_hit	boolean	필수	—
meta.billing.amount_credits	integer	필수	Credits actually charged for this request (the settlement unit; 1 credit = $0.0001, permanent).

필드 비고는 계약 영문 원문으로 표시됩니다.

응답 메타데이터

필드	타입	필수	설명
mode	cache \| default \| live	필수	Effective mode after merging param > max_age > source policy (D-004).
age_seconds	integer \| null	선택	Age of served data; null when unknown.
source_layer	cache \| db \| upstream	필수	Which layer served the response (PRD §10).
stale	boolean	선택	True when stale data was served under stale_if_error / SWR (D-004).
billing.amount_credits	integer	필수	Micro-USD (1e-6 USD) actually charged for this request.
billing.cache_hit	boolean	필수	—

필드 비고는 계약 영문 원문으로 표시됩니다.

요청·응답 예시

GET/v1/threads/search/users

curl -H "Authorization: Bearer $MESHDATA_API_KEY" \
  "https://api.fetchpi.com/v1/threads/search/users?q=meshdata"

{
  "data": [
    {
      "id": "7455000122",
      "platform": "threads",
      "type": "profile",
      "username": "meshdata",
      "display_name": "MeshData Threads",
      "description": "Threads 数据开放。",
      "profile_image_url": "https://cdn.example.com/avatar/threads-meshdata.jpg",
      "verified": true,
      "created_at": "2021-07-06T00:00:00Z",
      "metrics": {
        "followers": 815000,
        "following": 310,
        "posts": 4200
      },
      "fetched_at": "2026-09-21T09:00:00Z"
    }
  ],
  "next_cursor": null,
  "query": "数据",
  "meta": {
    "request_id": "req_01HTXQ8Z9HTQ",
    "freshness": {
      "mode": "default",
      "age_seconds": 0,
      "source_layer": "upstream",
      "stale": false
    },
    "billing": {
      "amount_credits": 300,
      "cache_hit": false
    }
  }
}

무료 데모

무료 계정을 만들고 API 키를 발급받으면 브라우저 Playground에서 바로 호출할 수 있습니다.

Playground에서 사용해 보기

이 엔드포인트의 파라미터 표, 오류 코드, 응답 의미는 API 문서에 있습니다.

엔드포인트 레퍼런스 열기

자주 묻는 질문

cache와 live 신선도의 차이는 무엇인가요?

cache는 저장된 스냅샷으로 응답하며 업스트림에 접근하지 않고, live는 더 신선한 데이터를 조회하며 추가 크레딧이 발생할 수 있습니다 — 자세한 내용은 문서의 신선도 섹션을 참조하세요.

이 엔드포인트를 무료로 써볼 수 있나요?

네 — 계정을 등록하고 API 키를 발급받으면 콘솔의 Playground에서 호출할 수 있습니다.

search_users 능력은 어떻게 과금되나요?

Data API는 요청 단위 크레딧 과금이며 cache/live 신선도에 따라 배율이 다릅니다. 현재 능력별 가격은 가격 페이지를 기준으로 합니다.

가격

요청 단위 크레딧 과금, cache/live 신선도 옵션 — 최신 가격은 가격 페이지 기준입니다.

가격 보기 모든 API 둘러보기