Twitter User Search API | Find Accounts by Keyword

User Search finds Twitter/X accounts by keyword, matching against display name and handle (X's People search does not search bio text). Results are cursor-paginated full user objects, useful for discovery, lead lists, and resolving a partial handle into a full profile. Each call costs $0.0008, the standard read rate, with no OAuth required.

curl -X GET "https://example.com/user/search?query=machine+learning&count=20&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"

{  "users": [    {      "id": "44196397",      "username": "elonmusk",      "name": "Elon Musk",      "description": "",      "followers_count": 211000000,      "verified": true    }  ],  "next_cursor": "DAABCgABF..."}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue.",  "top_up_url": "https://www.twitterapis.com/dashboard/buy-credits?utm_source=api&utm_medium=402"}

{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

Each page of results is one $0.0008 read, so a deep discovery crawl spends per page. Page only as far as your list needs.

When to use

Use it for account discovery, lead building and resolving partial handles, for example finding profiles whose display name mentions machine learning. To find people by what their bio says (a company @mention, a job title), pull that company's followers with User Followers, or search tweets mentioning it with Advanced Tweet Search, then filter the returned description field.

Pagination

This endpoint is cursor-paginated and returns roughly 20 records per call. Pass the next_cursor from each response back as the cursor parameter to read the next page. Stop when the records array comes back empty: follower-graph endpoints return a non-null cursor even on the final page, so the empty array is the only reliable stop signal. See Pagination for the full loop.

Related endpoints

• Advanced Tweet Search: Search tweets with Twitter's full query-operator syntax, paginated with cursors.
• User Info by Username: Fetch a full profile by @handle.
• User Followers: Page through the accounts that follow a user.

FAQ

What fields does User Search match against?

The display name and the @handle. X's People search does not match bio text, so a term that appears only in a bio (for example a job title or a company @mention) returns no match. Every result still carries its bio in the description field.

How do I find accounts whose bio mentions a company or keyword?

Pull the company's followers with User Followers, or search tweets that mention it with Advanced Tweet Search, then filter for the term. User Followers returns full user objects, and every tweet from Advanced Tweet Search carries its author profile with the bio in author.description.

Can I resolve a partial handle to a full profile?

Yes. Search the partial handle, then pass the resolved username to User Info by Username for the complete profile object.

How are results paginated?

Results come back cursor-paginated. Send the next_cursor from a response as the cursor parameter to fetch the next page.