Twitter User Search
Discovering relevant creator, company, and expert profiles on X requires targeted keyword matching across account handles and bios. Normalized profile results deliver usernames, display names, bios, location context, follower counts, and verification badges.
Features
- Keyword account matchingSubmit any query term to discover relevant public profiles across names, usernames, and account bios.
- Normalized profile attributesReceive consistent objects with user ID, handle, display name, avatar, banner, and biography text.
- Audience metricsCapture current follower, following, total post, media, and favorites counts for each returned account.
- Verification and status flagsIdentify blue verified badges, automated bot flags, protected account status, and location strings.
Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Search keyword query to find matching public X user profiles. |
results_limit | Optional | Maximum number of user profiles to return; must be a multiple of 20 between 20 and 2,000, defaulting to 20. |
How to Use
Submit a keyword search query as an asynchronous task, then paginate through normalized user profiles.
- Set your search term in query and specify results_limit as a multiple of 20 (up to 2,000).
- Send a POST request to /v1/x/search-users with your SocQ API key.
- Poll /v1/tasks/{task_id} until the task status is succeeded.
- Retrieve normalized account records from data.results.items.
curl -X POST "https://api.socq.ai/v1/x/search-users" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"OpenAI","results_limit":20}'
# Poll GET /v1/tasks/{task_id}, then fetch data.results.items.Best Use Cases
- Influencer and subject-matter expert discovery: Find influential domain experts, journalists, and thought leaders by searching industry terminology.
- Brand account auditing: Discover brand handles, localized regional subsidiaries, or unofficial fan accounts across the platform.
- Outreach prospect list generation: Build prospective lead lists of relevant professionals filtered by keywords in their public bio.
Pro Tips
- Use this endpoint to discover accounts; use X Search when you want to find individual tweets or posts.
- results_limit must be a multiple of 20 (e.g. 20, 40, 100) to align with upstream pagination batches.
- Check the is_verified and verified_type properties to confirm whether an account is officially authenticated.
- Pass discovered usernames into X User Posts or X Following List to further explore their audience graph.
Related APIs
Use these APIs when you need a different type of public X data.
- Twitter Tweet Scraper API — Retrieve public post text, authors, engagement, media, hashtags, mentions, and conversation relationships from x.com or twitter.com status URLs.
- Twitter Profile Scraper API — Retrieve public account identity, biographies, avatars, cover images, account status, and visible audience statistics by username.
- Twitter User Tweets Scraper API — Collect recent public posts, authors, media, hashtags, mentions, and engagement by username with replies excluded.
- Twitter Search API — Find public posts by search expression with latest or top ordering and a configurable result limit.
- X Followers List API — Collect public follower account identities and visible profile metrics for one or more X usernames.
- X Following List API — Collect profiles followed by public X accounts, including identity, biographies, account signals, visible counters, and source usernames.
- X Post Quotes API — Collect public quote posts for known status URLs with commentary, authors, engagement, media, timestamps, and source-post context.
- X Post Replies API — Collect public replies from X post URLs with selectable ordering, reply text, authors, visible engagement, media, and parent-post context.
- X Post Retweeters API — Collect a task-level unique set of normalized public profiles for accounts that reposted known X or Twitter status URLs.
- X Trends API — Collect current public X trend snapshots for known numeric WOEIDs with source rank, query, description, and location context.
- Twitter Mentions API