Fetch a user profile by handle
Retrieve a Twitter user profile and top-level account metadata by handle. Includes bio, follower/following counts, join date, and verification status. An account that does not exist is a 404 user_not_found ("No X account with handle @x."), and so is a suspended one (the error says it is suspended); a 404 is final, not retryable, and not billed (2026-11-13; before, it was a retryable 503).
/user-profile-details Profile https://api.fetchlayer.dev/twitter/user-profile-details Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
handle string required Twitter handle without @.
timeoutMs integer optional Time limit for the whole request, in milliseconds (1000–120000; values outside are brought into that range). It can only shorten the time a request may take, which is about 90 seconds at most. With maxItems, a call that runs out returns the pages it has, billed for those, with hasMore and nextCursor; a call with nothing to return yet fails with a 503 you can retry. We answer at the latest about 2 seconds before timeoutMs runs out (15% of it, at least 0.75 s, for limits under 13 seconds), so you can set it to your own client’s timeout. Left out, the request takes the time it needs.
Response Fields
user-profile-details
Fetch a user profile by handle
scrapedAt string ISO 8601 time the result was produced.
transport string The data source: always the platform id, "twitter".
entityType string Always twitter-user-profile-details.
cached boolean Present (true) only when the answer is a recent copy rather than a fresh read; scrapedAt then says when it was read. Only for a public profile, and at most 10 minutes old.
profile object | null The account; null when it could not be found.
profile.id string | null Numeric account id, as a string. It stays the same when the handle changes.
profile.name string | null Display name.
profile.handle string | null Handle without the @.
profile.description string | null Bio text.
profile.location string | null Location as the account wrote it.
profile.followersCount integer | null Followers.
profile.followingCount integer | null Accounts followed.
profile.tweetsCount integer | null Posts, replies included.
profile.mediaCount integer | null Posts with media.
profile.verified boolean | null Whether the account carries a verification checkmark (see verification for which kind).
profile.avatarUrl string | null Profile image URL.
profile.bannerUrl string | null Header image URL, or null.
profile.createdAt string | null When the account was created, as X writes it: "Wed Dec 19 20:20:32 +0000 2007" (UTC).
profile.favoritesCount integer | null Posts the account has liked.
profile.listedCount integer | null Lists the account is on. Currently always null: X no longer sends it.
profile.fastFollowersCount integer | null Currently always null: X no longer sends it. Use followersCount.
profile.normalFollowersCount integer | null Currently always null: X no longer sends it. Use followersCount.
profile.creatorSubscriptionsCount integer | null Creator subscriptions the account has, or null when X leaves it out.
profile.pinnedTweetIds string[] Ids of the pinned posts; empty when none.
profile.website object | null The website link on the profile; null when there is none.
profile.website.url string | null The t.co short link.
profile.website.expandedUrl string | null The full address it leads to.
profile.website.displayUrl string | null The shortened form X displays, e.g. nasa.gov.
profile.descriptionUrls object[] Links in the bio, expanded; empty when none.
profile.descriptionUrls[].url string | null The t.co short link.
profile.descriptionUrls[].expandedUrl string | null The full address it leads to.
profile.descriptionUrls[].displayUrl string | null The shortened form X displays, e.g. nasa.gov.
profile.avatarUrlLarge string | null The profile image at 400x400.
profile.verifiedType string | null The kind of verification, e.g. Business or Government; null for none.
profile.protected boolean | null True when the account’s posts are visible to its followers only.
profile.profileLabel object | null The affiliation badge shown next to the name (e.g. an organisation’s); null when there is none.
profile.profileLabel.description string | null The badge’s label, e.g. the organisation’s name.
profile.profileLabel.badgeUrl string | null The badge image.
profile.profileLabel.url string | null Where the badge links to.
profile.profileLabel.urlType string | null X’s link type, e.g. DeepLink.
profile.profileLabel.displayType string | null How X shows it, e.g. Badge.
profile.profileLabel.type string | null X’s label type, e.g. BusinessLabel.
profile.verification object Which verification the account has.
profile.verification.blue boolean | null Verified through a subscription (the blue checkmark).
profile.verification.verified boolean | null Verified by X as notable (legacy verification).
profile.verification.identityVerified boolean | null The account holder’s identity was verified; null when X does not say.
profile.verification.reason string | null X’s own explanation of the checkmark, e.g. for a government account; null when it gives none.
Request
curl -X POST "https://api.fetchlayer.dev/twitter/user-profile-details" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"handle":"NASA"}'Response
{
"entityType": "twitter-user-profile-details",
"profile": {
"id": "11348282",
"name": "NASA",
"handle": "NASA",
"description": "Making the seemingly impossible, possible. ✨",
"location": "Pale Blue Dot",
"followersCount": 92312272,
"followingCount": 115,
"tweetsCount": 74455,
"mediaCount": 28207,
"verified": true,
"avatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg",
"bannerUrl": "https://pbs.twimg.com/profile_banners/11348282/1788992290",
"createdAt": "Wed Dec 19 20:20:32 +0000 2007",
"favoritesCount": 17049,
"listedCount": null,
"pinnedTweetIds": [],
"profileLabel": null,
"verification": {
"blue": true,
"verified": false,
"identityVerified": false,
"reason": "This account is verified because it is a government or multilateral organization account."
}
},
"scrapedAt": "2026-10-25T19:14:00.000Z",
"transport": "twitter"
}