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

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": [
    {}
  ],
  "has_next_page": true,
  "next_cursor": "<string>"
}

integer

Require this minimum follower count. Filtering happens before billing.

integer

Allow this maximum follower count. Missing counts pass.

integer

Require this minimum account age in whole days.

boolean

When true, only return verified profiles.

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 profilesById = new Map(data.users.map((user) => [user.id, user]));
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 missingIds = ids.filter((id) => !profilesById.has(id));

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()
profiles_by_id = {user["id"]: user for user in data["users"]}
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"]
]
missing_ids = [user_id for user_id in ids if user_id not in profiles_by_id]

The Node.js and Python snippets shape durable profile rows instead of printing full profile objects. Persist profileRows or profile_rows and missingIds or missing_ids with the original ID list so retries only request missing profiles.

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 and needs profile details in one JSON response. 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 instead of relying 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

Compare returned user_id values with requested_ids. Retry only the missing IDs or route username-only inputs to Get User first.

No pagination

Use the single-page batch contract: has_next_page: false and next_cursor: "". Do not treat it as a cursor workflow.

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 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/batch 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.

Treat missing IDs explicitly. 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. This makes a failed enrichment job safe to resume.

Query parameters

string

required

Comma-separated user IDs. Maximum 100 per request.

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.

string

Account creation date (ISO 8601).

number

Total number of tweets posted. Omitted if unavailable.

string

Cover/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 the account is flagged as possibly sensitive. Omitted if unavailable.

string[]

IDs of pinned tweets. Omitted if none.

boolean

Whether the account is marked 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 (e.g. 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.

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

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 }

Your tier rate limit was exceeded. 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"
  ],
  "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."
}

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": [
    {}
  ],
  "has_next_page": true,
  "next_cursor": "<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

​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

401 Unauthenticated

402 Payment required

502 X API unavailable

429 Rate limit exceeded

424 Dependency failed