TwitterAPIs Docs
API ReferenceUser Reads

Twitter User Lookup API | Profile by Username

Resolve a username into the full user object: bio, follower and following counts, verification status, location, and avatar. The canonical entry point for profile lookups. Cost: $0.0008 per call.

User Info by Username resolves a Twitter/X @handle into the full user object: bio, follower and following counts, verification status, location, tweet count, account creation date, and avatar URL. It is the canonical entry point for profile lookups, a single $0.0008 read with bearer auth and no OAuth.

GET
/user/info

Authorization

bearerAuth
AuthorizationBearer <token>

Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.

In: header

Query Parameters

username*string

Handle without the leading @.

fields?string

Comma-separated list of dotted field paths to keep in the response (one parameter, never repeated), applied to every object in the returned lists and to nested objects (for example fields=id,text,author.username; the list's own name may prefix a path, fields=tweets.id). A path prefix that lands on an array applies to each element (media.media_url_https). Pagination and envelope keys (next_cursor, cursor, has_more, count, partial, error, message, reason) are always kept. Unknown paths are ignored; up to 50 paths of up to 6 segments. Projection never changes status codes or billing, and applies to data reads only: account, feedback, session status, monitor (other than deliveries), webhook and stream-compat reads return their bodies unchanged.

compact?string

Set to 1 (or true) to apply the built-in compact preset: ids, url, text, created_at, lang, the engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. The preset trims what it recognises and leaves alone what it would empty, so it never turns a body into {}. Combine with fields to add paths on top of the preset. Typically cuts a tweet page by 70 to 90 percent for LLM tool callers.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/user/info?username=naval&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"
{  "user": {    "id": "745273",    "username": "naval",    "name": "Naval",    "description": "Angel investor.",    "followers_count": 2100000,    "following_count": 421,    "verified": true,    "profile_image_url": "https://pbs.twimg.com/profile_images/.../avatar.jpg"  }}
{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}
{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}
{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue.",  "top_up_url": "https://www.twitterapis.com/dashboard/buy-credits?utm_source=api&utm_medium=402"}
{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}
{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}
{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}
{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

UnitPrice
Per call$0.0008
Per 1,000 calls$0.80

When to use

Use it as the first call in most profile workflows, for example resolving a handle into follower counts and verification status.

FAQ

What does User Info by Username return?

The full user object: bio, follower and following counts, verification, location, tweet count, creation date, and the avatar image URL.

Should I store the handle or the ID?

Store the numeric id. Handles can change, but the ID is stable. Re-resolve later with User Info by ID.

How much does a profile lookup cost?

It is one $0.0008 read per profile. Cache profiles that rarely change rather than refetching on every render.

Was this page helpful?