Twitter User Profile API - Get Profile by Handle

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).

POST /user-profile-details Profile
https://api.fetchlayer.dev/twitter/user-profile-details
OpenAPI JSON

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"
}
Product overview Twitter API: what it returns, pricing and use cases