threads/
search-users

The Threads User Search API finds accounts by name or username, returning the matches Threads suggests, usually up to 10, with username, display name, profile URL, avatar and verified status.

Threads User Search API

Name or username query
Up to about 10 matches
Verified status
0.6 credits / result
Ready
Ready

Enter parameters and send a request. The task status and normalized results will appear here.

README

By SocQ · Updated

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

ParametersRequiredDescription
queryRequiredA 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.

  1. POST {"query": "shams"} to /v1/threads/search-users.
  2. Poll GET /v1/tasks/{task_id} with the returned task_id until the status is succeeded.
  3. 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.

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.

Explore other platforms

Combine Threads data with public data from other supported social platforms.

Threads User Search API — FAQ

Threads User Search API is a programmatic interface for finding Threads accounts from a name or username. It returns the accounts Threads suggests, each with username, display name, profile link, avatar and verification status.

Usually up to 10, the same set of suggestions Threads offers for the name or username you entered.

Search results are built for identifying accounts. Send the url of each match to Threads Profiles API to collect its bio, website and visible follower counts.

The Threads User Search API charges 0.6 credits for each account returned, so a search with 10 matches costs 6 credits.