# Threads Search Users API (https://www.socialcrawl.dev/platforms/threads/search-users)

> Searches Threads for user accounts matching a query. Returns up to about 10 matching accounts with the handle, display name, avatar and verification status. A plain call is that identity window for 1 credit, and `author.followers`, `author.bio`, `author.private` and `author.ext.bio_link` stay null: the search index does not carry them. Send `include=profile` to fill them by row hydration: each account is looked up on `/v1/threads/profile` by its handle in the same call, and only those four leaves are copied onto the row, so nothing already on it changes. It costs 1 credit per account filled, adds 3 to 6 seconds (never more than 12), and a `data.hydration` block reports the rows looked up, filled and served from cache and the credits held and kept; an account the lookup could not fill is refunded and named by `data._warnings: ["profile_partial"]`. `limit` (1 to 12) takes the top N accounts and caps the extra credits with them. `include_details=true`, the older spelling, is the same call at the same price. Post count and join date stay null either way: Threads does not publish them. `author.url` is the account's Threads permalink, built from the handle.

TL;DR: `GET /v1/threads/search/users` costs 1 credit for the identity window, which is what a call with no `include` costs. With `include=profile` the call holds 1 credit per row of the page (12, or `limit`) and keeps 1 for each account it filled from a fresh lookup; accounts served from the profile lookup's cache (15 minutes) are free and the rest is refunded, so a call costs 13 at most and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search keyword or phrase to find Threads users |
| `include` | no | Send `profile` to fill `author.followers`, `author.bio`, `author.private` and `author.ext.bio_link` on each account by looking it up on `/v1/threads/profile` in the same call. 1 credit per account filled from a fresh lookup (12 at most, or `limit`); accounts served from that lookup's cache (15 minutes) and accounts it could not fill are free. Adds 3 to 6 seconds, never more than 12. One token only: `profile`. (profile) |
| `limit` | no | Take the top N accounts of the page, 1 to 12. With `include=profile` it also caps the extra credits: `limit=5&include=profile` holds 6 credits, not 13. A plain call with `limit` still costs 1. |
| `include_details` | no | The older spelling of `include=profile`, kept working: `include_details=true` runs the same join at the same price (1 credit per account filled, 13 at most), and `false` is the plain call. Prefer `include=profile` in new code. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/threads/search/users" \
  --data-urlencode "query=tech" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I find Threads users by keyword?

Send a GET request to /v1/threads/search/users with a query parameter. SocialCrawl returns about ten matching accounts with the handle, display name, avatar URL, verification status and profile URL, which is everything you need to shortlist candidates before enriching them.

### What data does each user result include?

Each result comes with the user id, handle, display name, avatar URL, verification status and profile URL, normalised into the same author schema every SocialCrawl platform uses. Follower count and bio are not part of the Threads account-search index, so they arrive null on a plain call; add include=profile and every account is looked up on the profile endpoint inside the same request, which fills the follower count, bio, private flag and bio link for 1 extra credit per account filled.

### How is this different from searching posts?

This endpoint finds user accounts that match your keyword; the search endpoint finds posts that match it. Use this to resolve a name to a handle and shortlist creators; use search for content and mention tracking.

### Can I filter the results by verification or follower count?

Verification status is on every result, so a verified-only shortlist is one client-side filter. Follower count is not carried by the Threads account-search index, so ask for it: include=profile fills the follower count and bio on every row in the same call, at 1 extra credit per account filled, and limit caps both the rows and the credits when you only want the top few. Then filter on the numbers client-side.

### How much does the Threads User Search API cost?

Each request costs 1 credit on the standard tier. New accounts get 100 free credits with no credit card required, enough to run 100 user searches before paying anything, great for prototyping creator workflows.

See the full Threads API: https://www.socialcrawl.dev/platforms/threads

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to find Threads users by keyword with an API
- What does the SocialCrawl Threads search/users endpoint return?