Skip to main content
GET https://xquik.com/api/v1/x/users/search
Requested result counts are upper bounds for paid authenticated calls. Remaining credits may not cover the full page or ID list. If so, Xquik returns fewer results. If zero paid results are affordable, it returns 402 insufficient_credits.
1 credit per result returned · All plans from $0.00012/credit
The Node.js and Python snippets build search-result rows. They do not print full profile pages. Store searchRows or search_rows with nextCursor or next_cursor before requesting the next page.

Direct user search handoff

Use GET /x/users/search when a workflow has a name, brand, or handle fragment. It can be a CRM, enrichment, creator discovery, support, or agent workflow. The endpoint returns matching X (Twitter) profiles. Use Get User when you have one exact ID or username. Use Get Users (Batch) when you already have numeric user IDs. Store search_query, result_rank, user_id, username, display_name, profile metrics, verification state, profile_image_url, has_next_page, and next_cursor. Treat next_cursor as opaque. And pass it back as cursor only when has_next_page is true. Zero affordable results return 402 insufficient_credits.

Resolve the intended X profile

Use user search when a workflow starts with a name or username fragment. Inspect several candidates before choosing a numeric user ID. Similar profile names can represent unrelated people or organizations. Show reviewers these fields.
  • Username and profile name.
  • Biography and location.
  • Verification state.
  • Follower and following counts.
  • Profile image and numeric user ID.
Store the chosen user ID for later requests. Usernames can change. Numeric IDs are the safer key for followers, following, timelines, and profile lookups. An empty search result is not an API failure. Separate no matches from invalid authentication, rate limits, and insufficient credits. Do not use a result row number as identity. Ranking can change between searches. Always pass the selected user ID into the next workflow.

Query parameters

User result filters

These filters apply before billing. Selective filters can return fewer rows.See user filters for every filter. Common ones are minFollowers, verifiedOnly, hasWebsite, hasEmail, bioContains, and locationContains.

Choose fields

Headers

Response

200 OK

With enrichProfiles=true, each row carries the full profile. The x-xquik-profile-enrichment header then counts the rows that have it, as in enriched=180; requested=200. A row without it keeps its list fields.

400 Missing query

{ "error": "missing_query" }

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.

402 Payment required

Account keys get account options. Guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

502 X API unavailable

The read service returned an error. Retry after a short delay.

429 Rate limit exceeded

You exceeded your tier rate limit. Wait for the Retry-After header before retrying.

424 Dependency failed

The normalized v1 response contract can return 424 when the read service is unavailable.
Next steps. Get User to fetch full details, or Search Tweets to find tweets by query.

Response examples

  • 400 { "error": "invalid_input", "message": "Invalid input. Check the request body." }
  • 401 { "error": "unauthenticated", "message": "Authentication required." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }
  • 403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
  • 424 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 502 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 503 { "error": "x_api_unavailable", "message": "Xquik is busy right now. Retry shortly." }