Twitter batch user lookup API & profile details

{
  "users": [
    {
      "id": "9876543210",
      "username": "elonmusk",
      "name": "Elon Musk"
    }
  ],
  "has_next_page": false,
  "next_cursor": "",
  "requested_count": 2,
  "processed_count": 2,
  "returned_count": 1,
  "unavailable_ids": [
    "1234567890"
  ],
  "failed_ids": [],
  "unprocessed_ids": []
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

GET

users

batch

Twitter batch user lookup API & profile details

curl --request GET \
  --url https://xquik.com/api/v1/x/users/batch

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/users/batch"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "users": [
    {
      "id": "<string>",
      "username": "<string>",
      "name": "<string>",
      "description": "<string>",
      "followers": 123,
      "following": 123,
      "verified": true,
      "profilePicture": "<string>",
      "location": "<string>",
      "accountBasedIn": {},
      "accountBasedInUnavailable": true,
      "createdAt": "<string>",
      "statusesCount": 123,
      "coverPicture": "<string>",
      "mediaCount": 123,
      "url": "<string>",
      "favouritesCount": 123,
      "hasCustomTimelines": true,
      "isTranslator": true,
      "withheldInCountries": [
        "<string>"
      ],
      "possiblySensitive": true,
      "pinnedTweetIds": [
        "<string>"
      ],
      "isAutomated": true,
      "automatedBy": "<string>",
      "unavailable": true,
      "unavailableReason": "<string>",
      "verifiedType": "<string>",
      "profile_bio": {},
      "isBlueVerified": true,
      "isVerified": true,
      "profileBannerUrl": "<string>",
      "protected": true,
      "communityRole": "<string>"
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>",
  "unavailable_ids": [
    "<string>"
  ],
  "failed_ids": [
    "<string>"
  ],
  "unprocessed_ids": [
    "<string>"
  ]
}

integer

Require this minimum follower count. Filtering happens before billing.

integer

Allow this maximum follower count. Missing counts pass this filter.

integer

Require this minimum following count.

integer

Allow this maximum following count. Missing counts pass this filter.

integer

Require this minimum post count.

integer

Allow this maximum post count. Missing counts pass this filter.

integer

Require this minimum account age in days.

boolean

When true, only return verified profiles.

string

Match the exact verification type.

boolean

When true, require a profile website.

boolean

When true, require a profile location.

string

Require every comma-separated or line-separated bio term.

string

Require this text in the profile location.

string

Require this text in the username.

Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page or ID list, 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

curl "https://xquik.com/api/v1/x/users/batch?ids=44196397,987654321" \
  -H "x-api-key: xq_your_api_key_here" | jq

const ids = ["44196397", "987654321"];
const response = await fetch(`https://xquik.com/api/v1/x/users/batch?ids=${ids.join(",")}`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const data = await response.json();
const profileRows = data.users.map((user) => ({
  user_id: user.id,
  username: user.username,
  display_name: user.name,
  bio: user.description ?? null,
  follower_count: user.followers ?? null,
  following_count: user.following ?? null,
  verified: user.verified ?? false,
  profile_image_url: user.profilePicture ?? null,
}));
const retryNow = data.failed_ids;
const retryAfterCredits = data.unprocessed_ids;

import requests

ids = ["44196397", "987654321"]
response = requests.get(
    "https://xquik.com/api/v1/x/users/batch",
    params={"ids": ",".join(ids)},
    headers={"x-api-key": "xq_your_api_key_here"},
)
data = response.json()
profile_rows = [
    {
        "user_id": user["id"],
        "username": user["username"],
        "display_name": user["name"],
        "bio": user.get("description"),
        "follower_count": user.get("followers"),
        "following_count": user.get("following"),
        "verified": user.get("verified", False),
        "profile_image_url": user.get("profilePicture"),
    }
    for user in data["users"]
]
retry_now = data["failed_ids"]
retry_after_credits = data["unprocessed_ids"]

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 CRM, warehouse, enrichment, lead scoring, or agent workflow already has numeric X user IDs. 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 at most 100 IDs per request. 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 with username, name, description, followers, following, verified, and verifiedType.

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 the usernames as sent, and a profile link by its username.

No pagination

A batch returns one page: 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 up to 100 comma-separated user IDs, usernames, or profile links in one request.

Name or partial handle

Use GET /x/users/search before batch lookup when the workflow starts from 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 follower, following, timeline, media, or search job instead of an existing ID list.

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. Useful enrichment fields include:

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

string

Comma-separated numeric user IDs. Maximum 100 per request. Send ids or usernames, not both.

string

Comma-separated X usernames, with or without @, or profile links such as x.com/nasa, in place of ids. Maximum 100 per request. A name in another case is the same account. A link & a username for 1 account are read once.

Headers

string

Full account key. Sessions and OAuth also work.

string

Bearer xq_your_guest_key_here for paid_reads.

Response

200 OK

object[]

Array of user profiles matching the requested IDs. User object fields.

string

X user ID.

string

X username.

string

Display name.

string

Profile bio.

number

Follower count.

number

Following count.

boolean

Verified status.

string

Profile image URL.

string

Profile location.

object | null

Country or region X shows for the account, with value, level & observedAt. X infers it from account access. It states no nationality or exact location. null when X shows none. Omitted when X withholds it.

boolean

true when X withheld accountBasedIn from this read. Retry later to get it. Omitted otherwise.

string

Account creation date (ISO 8601).

number

Total number of tweets posted. Omitted if unavailable.

string

Cover or banner image URL. Omitted if unavailable.

number

Total number of media tweets posted. Omitted if unavailable.

string

Website URL from profile. Omitted if empty.

number

Total number of tweets liked. Omitted if unavailable.

boolean

Whether the user has custom timelines. Omitted if unavailable.

boolean

Whether the user is an X translator. Omitted if unavailable.

string[]

Country codes where the account is withheld. Omitted if empty.

boolean

Whether X flags the account as possibly sensitive. Omitted if unavailable.

string[]

IDs of pinned tweets. Omitted if none.

boolean

Whether X marks the account as automated. Omitted if unavailable.

string

Username of the account operator if automated. Omitted if not automated.

boolean

Whether the account is unavailable. Omitted if available.

string

Reason the account is unavailable. Omitted if available.

string

Verification type (for example Business, Government). Omitted if not verified or standard blue check.

object

Structured profile bio with entity annotations. Omitted if unavailable.

boolean

Whether the account has X Premium verification. Omitted if unavailable.

boolean

Normalized verification status. Omitted if unavailable.

string

Profile banner URL. Omitted if unavailable.

boolean

Whether the account protects its posts. Omitted if unavailable.

string

Role within the requested community context. Omitted outside community results.

boolean

Always false for batch requests.

string

Always empty for batch requests.

string[]

IDs with no profile on X. Skip them.

string[]

IDs that failed to load. They cost nothing. Retry them.

string[]

IDs skipped for low credits. Retry them after adding credits.

{
  "users": [
    {
      "id": "44196397",
      "username": "elonmusk",
      "name": "Elon Musk",
      "followers": 200000000,
      "verified": true
    }
  ],
  "has_next_page": false,
  "next_cursor": ""
}

400 Missing IDs

{ "error": "missing_ids", "message": "ids parameter required" }

400 Too many IDs

{ "error": "too_many_ids", "message": "Max 100 IDs per request" }

400 Invalid usernames

{
  "error": "invalid_user_ids",
  "message": "usernames must contain 1-100 X usernames or profile links such as x.com/nasa."
}

Each usernames value must be a username or a link to a profile on x.com or twitter.com. A post link, a user ID link, another site, and the text undefined or null answer 400. 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.

{ "error": "unauthenticated" }

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

{ "error": "x_api_unavailable" }

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

429 Rate limit exceeded

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

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

424 Dependency failed

{ "error": "x_api_unavailable" }

The normalized v1 response contract can return 424 when the read service is unavailable.

Related. Batch Tweets · Get User

{
  "users": [
    {
      "id": "9876543210",
      "username": "elonmusk",
      "name": "Elon Musk"
    }
  ],
  "has_next_page": false,
  "next_cursor": "",
  "requested_count": 2,
  "processed_count": 2,
  "returned_count": 1,
  "unavailable_ids": [
    "1234567890"
  ],
  "failed_ids": [],
  "unprocessed_ids": []
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

Twitter batch user lookup API & profile details

curl --request GET \
  --url https://xquik.com/api/v1/x/users/batch

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/users/batch"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "users": [
    {
      "id": "<string>",
      "username": "<string>",
      "name": "<string>",
      "description": "<string>",
      "followers": 123,
      "following": 123,
      "verified": true,
      "profilePicture": "<string>",
      "location": "<string>",
      "accountBasedIn": {},
      "accountBasedInUnavailable": true,
      "createdAt": "<string>",
      "statusesCount": 123,
      "coverPicture": "<string>",
      "mediaCount": 123,
      "url": "<string>",
      "favouritesCount": 123,
      "hasCustomTimelines": true,
      "isTranslator": true,
      "withheldInCountries": [
        "<string>"
      ],
      "possiblySensitive": true,
      "pinnedTweetIds": [
        "<string>"
      ],
      "isAutomated": true,
      "automatedBy": "<string>",
      "unavailable": true,
      "unavailableReason": "<string>",
      "verifiedType": "<string>",
      "profile_bio": {},
      "isBlueVerified": true,
      "isVerified": true,
      "profileBannerUrl": "<string>",
      "protected": true,
      "communityRole": "<string>"
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>",
  "unavailable_ids": [
    "<string>"
  ],
  "failed_ids": [
    "<string>"
  ],
  "unprocessed_ids": [
    "<string>"
  ]
}

​Direct batch user handoff

Known IDs

Profile rows

Missing rows

No pagination

​Which lookup endpoint?

One profile

Many known IDs

Name or partial handle

Tweet IDs

Audience pages

Saved exports

​Enrich a known set of user IDs

​Query parameters

​Headers

​Response

​200 OK

​400 Missing IDs

​400 Too many IDs

​400 Invalid usernames

​401 Unauthenticated

​402 Payment required

​502 X API unavailable

​429 Rate limit exceeded

​424 Dependency failed

Direct batch user handoff

Which lookup endpoint?

Enrich a known set of user IDs

Query parameters

Headers

Response

200 OK

400 Missing IDs

400 Too many IDs

400 Invalid usernames

401 Unauthenticated

402 Payment required

502 X API unavailable

429 Rate limit exceeded

424 Dependency failed