Skip to main content
GET
Twitter profile search, lookup & audience counts
1 credit per call · All plans from $0.00012/credit · Direct MPP: USD 0.00015 per call
See Read Data Richness for every optional profile field. Xquik omits fields that X does not supply.
Use GET /x/users/{id} when a workflow needs one profile row for CRM enrichment, lead scoring, account monitoring, or support triage. Store user_id, username, display_name, bio, follower_count, following_count, verified, verified_type, profile_url, profile_image_url, created_at, and unavailable_reason. Do not log the full lookup response.

Profile row

Store id as user_id plus username, name, description, followers, following, verified, and verifiedType.

Lookup key

Join on the numeric user ID, which does not change. Use username lookup when the workflow starts from a handle.

Availability

Store unavailable and unavailableReason when returned. Retries, support triage, and CRM syncs can then distinguish missing accounts from unavailable profiles.

Next action

Use the returned id for followers, following, timelines, media, DMs, follow checks, and monitor setup.

Store a Twitter profile lookup

Keep the numeric X user ID as the stable key. Profile usernames, names, bios, counts, verification, locations, links, and images can change between lookups.

Path parameters

string
required
User ID, username with or without @, or URL-encoded profile URL, such as x.com/nasa. See path IDs.

Which user endpoint?

User profile

Use GET /x/users/{id} for one profile row by username or numeric user ID.

Search users

Use GET /x/users/search when the workflow starts from a name, keyword, or partial handle.

Profile timeline

Use GET /x/users/{id}/tweets for posts from one profile.

Followers

Use GET /x/users/{id}/followers when the next step needs audience rows.

Follow check

Use GET /x/followers/check when the workflow only needs one source-target relationship.

Saved exports

Use Create extraction. Create saved CSV, JSON, or XLSX jobs. Export followers, following, timelines, media, or search.

Headers

string
Full account key. Sessions and OAuth also work.
string
Bearer xq_your_guest_key_here authenticates paid_reads guest keys. Direct MPP uses the Payment ... credential. Get it from the WWW-Authenticate: Payment challenge.

Response

200 OK

string
User ID.
string
X username.
string
Display name.
string
Profile bio. Omitted if empty.
number
Follower count. Omitted if unavailable.
number
Following count. Omitted if unavailable.
boolean
Whether the user is verified. Omitted if unavailable.
string
Profile picture URL. Omitted if unavailable.
string
Profile location. Omitted if empty.
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.
boolean
false when X notes that accountBasedIn may be inaccurate. Omitted if unavailable.
string
How the account first connected to X, such as United States App Store. Omitted if unavailable.
boolean
false when X notes that the connectedVia country may be inaccurate. Omitted if unavailable.
object
How often the account changed its username: count and, when there was a change, lastChangedAt. Omitted if unavailable.
object
The parts of the birthday the account made public: day, month, and year. Omitted if unavailable.
string
ISO 8601 account creation timestamp. Omitted if unavailable.
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 (lists). Omitted if unavailable.
boolean
Whether the user is a Twitter 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 (suspended, deactivated). 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 a returned community context. Omitted outside community results.
number
Public lists that include the profile. Omitted if unavailable.
number
Followers X counts as fast followers. Omitted if unavailable.
number
Followers minus fast followers. Omitted if unavailable.
number
Accounts subscribed to the profile’s paid Subscriptions. 0 when it has none. Omitted if unavailable.
boolean
Whether the profile keeps X’s default theme. Omitted if unavailable.
boolean
Whether the profile keeps X’s default avatar. Omitted if unavailable.
boolean
Whether the profile may add a location to posts. Omitted if unavailable.
boolean
Whether the profile filled X’s extended fields, such as a birth date. Omitted if unavailable.
boolean
Whether the account turned on X’s translation of its posts. Omitted if unavailable.
string
The account’s X Ads type. none for an account without ads, or promotable_user for one that may run them. Omitted if unavailable.
string[]
X Ads services the account uses, such as analytics, media_studio or smb. Empty for an account without ads. Omitted if unavailable.
string
Whether X treats the profile as a business profile. none or enabled. Omitted if unavailable.
object
X’s text on why the profile is verified, with the entities that link parts of it. Omitted if unavailable.

400 Invalid user ID

The path names no user. Send a user ID, username or profile URL.

401 Unauthenticated

Missing or invalid API key. Check the x-api-key header value.

402 Payment required

Account keys get account options. Guest keys get guest top-up only. Anonymous calls receive a direct MPP WWW-Authenticate: Payment challenge plus a guest wallet creation action. No checkout starts automatically. Confirm any payment action.

404 User not found

X shows no profile for the user. The answer adds reason: not_found, or suspended when X suspended the account. Check the username or choose another account.

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. Check Follower to verify follow relationships, or Search Tweets to find tweets from this user.