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.
Authorization
bearerAuth Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.
In: header
Query Parameters
Handle without the leading @.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/user/info?username=naval"{ "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."}{ "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
| Unit | Price |
|---|---|
| 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.
Related endpoints
- User Info by ID: Fetch a full profile by numeric user ID.
- User Followers: Page through the accounts that follow a user.
- User Following: Page through the accounts a user follows.
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.
Overview
User Reads: Read a profile, its timeline, media, mentions, affiliates, and follow relationships by username or numeric ID.
User Info by ID GET
Resolve a numeric user ID into the full user object. Use this when you already have the stable ID (handles can change, IDs do not). Cost: $0.0008 per call.