> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/threads/users-search>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/threads/users-search.mdx>

---

# Threads User Search API

Discover public Threads accounts by keyword — handle, display name, avatar, and verification in structured JSON, without a Meta Threads developer app.

`GET /v1/threads/users/search` takes a required `query` string (max 512 characters after trim) and returns matching public accounts under `data.users`, with `data.query` echoed and `data.totalUsers` set to the count in that response. Each hit can include `handle`, `displayName`, `avatarUrl`, `verified`, `profileUrl`, and optional fields such as `platformUserId`, `activeOnThreads`, and `onboardedToThreads`. Bill from `meta.creditsCharged` and keep `meta.requestId` when a row looks wrong.

This route is people discovery. Keyword post search is `GET /v1/threads/search`. Once you have a handle, use `GET /v1/threads/profiles/{handle}` for the full profile card. There is no cursor pagination on this operation — one response per query. Pricing is 1 credit per successful request.

## Request

- **Endpoint:** `GET /v1/threads/users/search`
- **Credits:** 1 credit
Failed requests are free
- **Input:** by query
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/threads/users/search/get)
- **Platform page:** [/platforms/threads](https://www.socialfetch.dev/platforms/threads)

## FAQ

### How do I search Threads users via API?

Call `GET /v1/threads/users/search` with your Social Fetch API key (`x-api-key`) and a required `query` parameter. Read `data.users`, `data.totalUsers`, and `data.query` in the JSON response. See the API docs for parameters and examples.

### How much does Threads user search cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.

### What fields does each Threads user search hit include?

Each user includes platform (`threads`), handle, displayName, avatarUrl, verified, and profileUrl. Optional fields can include platformUserId, activeOnThreads, and onboardedToThreads when Threads exposes them.

### User search vs Threads post search?

Use `GET /v1/threads/users/search` to find people by keyword. Use `GET /v1/threads/search` to find posts by keyword. They are separate operations on the Threads hub.

### Does Threads user search support cursor pagination?

No. This operation returns one result set for the query. There is no `cursor` or `nextCursor` parameter. Tighten the query if you need a smaller candidate list.

### What should I call after I find a matching handle?

Follow a hit with `GET /v1/threads/profiles/{handle}` when you need the full public profile card, then `GET /v1/threads/profiles/{handle}/posts` if you need recent posts. Keep `meta.requestId` from the search response if a later enrichment row looks wrong.

### Do I need a Meta Threads developer app?

No. You authenticate to Social Fetch with an API key. The route reads public user search results; it does not act on behalf of a logged-in Threads user or require Meta app review for these lookups.