Users
Twitter Profile Search, Lookup & Audience Counts
Search a Twitter or X profile by username or user ID. Retrieve the bio, follower and following counts, verification status, location, and links. See costs.
GET
Twitter Profile Search, Lookup & Audience Counts
GET /x/users/{id} when a workflow needs one durable 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 instead of logging
the full lookup response.
Profile row
Store
id as user_id plus username, name, description, followers,
following, verified, and verifiedType.Lookup key
Use a numeric user ID for durable joins. Use username lookup when the
workflow starts from a handle.
Availability
Store
unavailable and unavailableReason when returned, so retries,
support triage, and CRM syncs 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 or username (without
@).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/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.
string
ISO 8601 account creation timestamp. Omitted if unavailable.
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 (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 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.
Whether the account is unavailable (suspended, deactivated). Omitted if available.
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 a returned community context. Omitted outside community results.
400 Invalid username
401 Unauthenticated
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 MPPWWW-Authenticate: Payment challenge plus a guest wallet creation action.
No checkout starts automatically. Confirm any payment action.
404 User not found
502 X API unavailable
429 Rate Limit Exceeded
Retry-After header before retrying.
424 Dependency Failed
Next steps: Check Follower to verify follow relationships, or Search Tweets to find tweets from this user.
Twitter Profile Search, Lookup & Audience Counts