Threads User Search
Threads user search is the list of accounts the app suggests for a typed name or handle, each identified by its username, display name, profile link, avatar and verification badge. Those identifiers let you tell a real person or brand apart from similarly named accounts and turn a plain list of names into confirmed Threads profiles.
Threads User Search API Features
- Matches on names and handlesquery accepts a display name or a username, and the response holds the accounts Threads suggests for it, usually up to 10.
- Identity fields ready to useEach match from the Threads User Search API returns username, name and url, the profile link in the /@username form that other Threads endpoints take as input.
- Badge and avatar for disambiguationis_verified and avatar_url help pick the genuine account when several matches share a name.
Threads User Search API Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | A person's or brand's name, or a Threads username, such as shams. |
How to Use the Threads User Search API
Search a name with the Threads User Search API and read the suggested accounts.
- POST {"query": "shams"} to /v1/threads/search-users.
- Poll GET /v1/tasks/{task_id} with the returned task_id until the status is succeeded.
- Read the matching accounts from results.items, following results.next_cursor whenever has_more is true.
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 Use Cases
- Confirming a handle before collecting content: Check username, display name and is_verified for the right match, then use its url to pull that account's posts, replies or reposts.
- Turning a name list into Threads profiles: Search each name on an influencer or press list and keep the verified match's url to build a column of Threads profile links.
- Spotting look-alike accounts: Search a brand or public figure and review the unverified matches with near-identical names and avatars for possible impersonators or fan pages.
Threads User Search API Pro Tips
- Try both the full name and a likely handle when the account you want is missing from the first set of matches, since query matches either.
- Choose a match on username plus is_verified rather than taking the first row, because common names return several similar accounts.
- Hand the chosen url straight to Threads User Posts, User Replies or User Reposts API, which all accept profile links in that same form.
Related APIs
Beyond the Threads User Search API, use these APIs when you need a different type of public Threads data.
- Threads Posts API — Collect public post text, author context, media, timestamps, and visible engagement from supported Threads post URLs.
- Threads Profiles API — Collect public profile identity, biographies, images, websites, visible account counts, and collection context from supported Threads profile URLs.
- Threads User Posts API — Discover public posts from Threads profile URLs with a per-profile limit, normalized content, authors, media, timestamps, visible engagement, and source context.
- Threads Post Replies API — Collect the replies under Threads posts from post URLs, with reply text, authors, like and reply counts, media and the ID of the post answered.
- Threads Search API — Search Threads by keyword or hashtag for the top posts, with text, authors, likes, replies, reposts, media and publish time.
- Threads User Replies API — Collect the latest public replies an account has posted from Threads profile URLs, with reply text, engagement, media and links.