Skip to main content
GET https://xquik.com/api/v1/x/users/batch See user filters for every filter. Common ones are minFollowers, verifiedOnly, hasWebsite, hasEmail, bioContains, and locationContains.
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 user returned · All plans from $0.00012/credit
The Node.js and Python snippets build profile rows. They do not print full profile objects. Store profileRows or profile_rows with the original ID list. Retry failed_ids now. Retry unprocessed_ids after adding credits. Skip unavailable_ids, which have no profile on X.

Direct batch user handoff

Use GET /x/users/batch when a workflow already has numeric X user IDs. It can be a CRM, warehouse, enrichment, lead scoring, or agent workflow. One JSON response returns the profile details. Use Get User when you have one ID or username to resolve. Store requested_ids, user_id, username, display_name, profile metrics, verification state, profile_image_url, has_next_page, and next_cursor. Join returned users by user_id. Do not rely on response order. Send as many IDs as fit in 1 URL. Batch requests always return has_next_page: false and next_cursor: "". Zero affordable results return 402 insufficient_credits.

Known IDs

Send comma-separated X user IDs in ids. Keep the original list as requested_ids for retry and audit rows.

Profile rows

Store each returned id as user_id. Store username, name, description, followers, following, verified, and verifiedType with it.

Missing rows

Retry failed_ids now & unprocessed_ids after adding credits. Skip unavailable_ids, which have no profile on X. With usernames, these lists name usernames as sent and profile links by their usernames.

No pagination

A batch returns one page, with has_next_page: false and next_cursor: "". Do not paginate it.

Which lookup endpoint?

One profile

Use GET /x/users/{id} for one username or one user ID.

Many known IDs

Use GET /x/users/batch for many comma-separated user IDs, usernames, or profile links. Send them in one request.

Name or partial handle

Use GET /x/users/search before batch lookup when you have a name, brand, or handle fragment.

Tweet IDs

Use GET /x/tweets?ids= when the input list contains tweet IDs instead of user IDs.

Audience pages

Use GET /x/users/{id}/followers or GET /x/users/{id}/following when the job starts from an account audience.

Saved exports

Use Create extraction when the source is a job instead of an existing ID list. It can be a follower, following, timeline, media, or search job.

Enrich a known set of user IDs

Use batch lookup after another workflow already identified exact profiles. Examples include follower exports, tweet authors, community members, or CRM records. Prepare one deduplicated ID list. Keep the original source beside each ID. After lookup, map every returned profile back to its source row. These enrichment fields are useful.
  • Current username and profile name.
  • Biography, location, and verification state.
  • Follower and following counts.
  • Profile image and account creation time.
Mark missing IDs as missing. Do not shift remaining profiles into another row’s position. Join responses by numeric user ID. Split oversized workloads into supported batches. Save each completed batch before starting the next. A failed enrichment job can then resume from the last saved batch.

Query parameters

Choose fields

Headers

Response

200 OK

400 Missing IDs

{ "error": "missing_ids", "message": "Send ids or usernames, such as ids=11348282 or usernames=nasa." }

400 Invalid usernames

{ "error": "invalid_user_ids", "message": "usernames must contain X usernames or profile links such as x.com/nasa." } Each usernames value must be a username or a profile link. Profile links must be on x.com or twitter.com. A post link, a user ID link, or another site answers 400. So does the text undefined or null. Send a user ID in ids. The request costs nothing.

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.

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." }