List Twitter profile tweets Returns up to roughly 100 of the account's most popular public tweets as ranked by X. This is not a chronological timeline and is not paginated with a cursor. For handle resolution, inspect `data.lookupStatus` (`found` vs `not_found`). An empty `data.tweets` array can still accompany `lookupStatus: "found"` when the account resolves but has no eligible tweets in this set—call `GET /v1/twitter/profiles/{handle}` first if you need `private` vs `not_found` for the account itself.
GET /v1/twitter/profiles/{handle}/tweets
Headers x-api-key string required (header)
API key (`sfk_...`)
Parameters handle string required
X handle to look up, with or without a leading @.
trim boolean (query)
Optional: omit per-tweet author and profile card for a smaller response.
Response fields Endpoint-specific response payload.
data . lookupStatus
string required
Whether tweet data was returned for this handle.
one of: found, not_found
data . profile
object required nullable
Profile card from the first tweet when full data is available; null when trimmed or not found.
data . profile . platform
string required
Social platform for this profile.
one of: twitter
data . profile . handle
string required
Screen name without @.
min 1 chars
data . profile . displayName
string required nullable
Display name for the profile.
data . profile . avatarUrl
string required nullable
Best available square avatar URL.
data . profile . verified
boolean required
Legacy verified flag from X.
data . profile . blueVerified
boolean required
Paid blue verification flag from X.
data . profile . profileUrl
string required
Canonical profile URL on x.com.
min 1 chars
data . profile . platformUserId
string
Numeric user id as a string.
Up to roughly 100 popular public tweets from X for this request (not chronological). May be empty when `lookupStatus` is `found` and no eligible tweets are returned, or when `lookupStatus` is `not_found`.
data . tweets [] . id
string required
Tweet id (`rest_id`).
min 1 chars
data . tweets [] . url
string required
Canonical public URL for this tweet on x.com.
min 1 chars
data . tweets [] . conversationId
string required
Conversation root tweet id.
min 1 chars
data . tweets [] . createdAt
integer required
Creation time as Unix epoch seconds.
≥ 0
data . tweets [] . language
string required
BCP 47 or X language code.
min 1 chars
data . tweets [] . text
string required
Full tweet text (includes long-form when available).
data . tweets [] . isLongForm
boolean required
True when text was taken from note_tweet metadata instead of legacy.full_text alone.
data . tweets [] . displayTextRange
array required
Start/end character indices for visible text.
data . tweets [] . displayTextRange []
integer
≥ 0
data . tweets [] . author
object required nullable
Author snapshot; null when `trim=true` omits per-tweet author data.
data . tweets [] . author . handle
string required
Author screen name without the leading @.
min 1 chars
data . tweets [] . author . displayName
string required nullable
Author display name.
data . tweets [] . author . avatarUrl
string required nullable
Best available square avatar URL for the author.
data . tweets [] . author . verified
boolean required
Whether X marks the author with legacy verification.
data . tweets [] . author . blueVerified
boolean required
Whether the author has X blue (paid) verification.
data . tweets [] . author . platformUserId
string
Numeric X user id for the author as a string.
data . tweets [] . metrics
object required
Engagement metrics for a tweet.
data . tweets [] . metrics . views
integer required
Impression count when reported by X.
≥ 0
data . tweets [] . metrics . favorites
integer required
Favorite (like) count.
≥ 0
data . tweets [] . metrics . retweets
integer required
Native repost count.
≥ 0
data . tweets [] . metrics . replies
integer required
Reply count.
≥ 0
data . tweets [] . metrics . bookmarks
integer required
Bookmark count.
≥ 0
data . tweets [] . metrics . quotes
integer required
Quote tweet count.
≥ 0
data . tweets [] . media
array required
Photo, video, or GIF attachments.
data . tweets [] . entities
object required
Entities aligned with `text`.
data . tweets [] . entities . hashtags
array required
Hashtag entities.
data . tweets [] . entities . hashtags [] . text
string required
Hashtag text without #.
data . tweets [] . entities . userMentions
array required
User mention entities.
data . tweets [] . entities . userMentions [] . handle
string required
Mentioned screen name.
min 1 chars
data . tweets [] . entities . userMentions [] . displayName
string
Display name when available.
data . tweets [] . entities . userMentions [] . platformUserId
string
Numeric user id for the mention when available.
data . tweets [] . entities . urls
array required
URL entities.
data . tweets [] . entities . urls [] . url
string required
Short URL as it appears in text.
min 1 chars
data . tweets [] . entities . urls [] . displayUrl
string required
Human-readable display host/path.
min 1 chars
data . tweets [] . entities . urls [] . expandedUrl
string required
Fully expanded destination URL.
min 1 chars
data . tweets [] . entities . symbols
array required
Symbol entities.
data . tweets [] . entities . symbols [] . text
string required
Cashtag or symbol text.
min 1 chars
data . tweets [] . isReply
boolean required
Whether this is a reply.
data . tweets [] . inReplyToTweetId
string
Parent tweet id when replying.
data . tweets [] . inReplyToUserId
string
Parent author user id when replying.
data . tweets [] . inReplyToScreenName
string
Parent author handle when replying.
data . tweets [] . isQuote
boolean required
Whether this tweet quotes another.
data . tweets [] . quotedTweetId
string
Quoted tweet id when present.
data . tweets [] . isRetweet
boolean required
Whether this is a native repost.
data . tweets [] . retweetedTweetId
string
Original tweet id for a repost.
data . tweets [] . possiblySensitive
boolean required
Whether X marks the content sensitive.
data . tweets [] . editInfo
object
Edit metadata when applicable.
data . tweets [] . editInfo . editTweetIds
array required
Tweet ids in this edit chain.
data . tweets [] . editInfo . editTweetIds []
string
min 1 chars
data . tweets [] . editInfo . editableUntilMsec
string required
Epoch milliseconds until edits are locked.
data . tweets [] . editInfo . isEditEligible
boolean required
Whether the tweet can still be edited.
data . tweets [] . editInfo . editsRemaining
string required
Remaining edits in the window, as reported by X.
data . tweets [] . source
string
Client label text (for example “Twitter for iPhone”).
data . tweets [] . sourceUrl
string
Link target from the source anchor when present.
data . tweets [] . quotedTweet
object
Expanded quoted tweet (one level deep).
data . tweets [] . quotedTweet . id
string required
Tweet id (`rest_id`).
min 1 chars
data . tweets [] . quotedTweet . url
string required
Canonical public URL for this tweet on x.com.
min 1 chars
data . tweets [] . quotedTweet . conversationId
string required
Conversation root tweet id.
min 1 chars
data . tweets [] . quotedTweet . createdAt
integer required
Creation time as Unix epoch seconds.
≥ 0
data . tweets [] . quotedTweet . language
string required
BCP 47 or X language code.
min 1 chars
data . tweets [] . quotedTweet . text
string required
Full tweet text (includes long-form when available).
data . tweets [] . quotedTweet . isLongForm
boolean required
True when text was taken from note_tweet metadata instead of legacy.full_text alone.
data . tweets [] . quotedTweet . displayTextRange
array required
Start/end character indices for visible text.
data . tweets [] . quotedTweet . displayTextRange []
integer
≥ 0
data . tweets [] . quotedTweet . author
object required nullable
Author snapshot; null when `trim=true` omits per-tweet author data.
data . tweets [] . quotedTweet . author . handle
string required
Author screen name without the leading @.
min 1 chars
data . tweets [] . quotedTweet . author . displayName
string required nullable
Author display name.
data . tweets [] . quotedTweet . author . avatarUrl
string required nullable
Best available square avatar URL for the author.
data . tweets [] . quotedTweet . author . verified
boolean required
Whether X marks the author with legacy verification.
data . tweets [] . quotedTweet . author . blueVerified
boolean required
Whether the author has X blue (paid) verification.
data . tweets [] . quotedTweet . author . platformUserId
string
Numeric X user id for the author as a string.
data . tweets [] . quotedTweet . metrics
object required
Engagement metrics for a tweet.
data . tweets [] . quotedTweet . metrics . views
integer required
Impression count when reported by X.
≥ 0
data . tweets [] . quotedTweet . metrics . favorites
integer required
Favorite (like) count.
≥ 0
data . tweets [] . quotedTweet . metrics . retweets
integer required
Native repost count.
≥ 0
data . tweets [] . quotedTweet . metrics . replies
integer required
Reply count.
≥ 0
data . tweets [] . quotedTweet . metrics . bookmarks
integer required
Bookmark count.
≥ 0
data . tweets [] . quotedTweet . metrics . quotes
integer required
Quote tweet count.
≥ 0
data . tweets [] . quotedTweet . media
array required
Photo, video, or GIF attachments.
data . tweets [] . quotedTweet . media []
data . tweets [] . quotedTweet . entities
object required
Entities aligned with `text`.
data . tweets [] . quotedTweet . entities . hashtags
array required
Hashtag entities.
data . tweets [] . quotedTweet . entities . hashtags [] . text
string required
Hashtag text without #.
data . tweets [] . quotedTweet . entities . userMentions
array required
User mention entities.
data . tweets [] . quotedTweet . entities . userMentions [] . handle
string required
Mentioned screen name.
min 1 chars
data . tweets [] . quotedTweet . entities . userMentions [] . displayName
string
Display name when available.
data . tweets [] . quotedTweet . entities . userMentions [] . platformUserId
string
Numeric user id for the mention when available.
data . tweets [] . quotedTweet . entities . urls
array required
URL entities.
data . tweets [] . quotedTweet . entities . urls [] . url
string required
Short URL as it appears in text.
min 1 chars
data . tweets [] . quotedTweet . entities . urls [] . displayUrl
string required
Human-readable display host/path.
min 1 chars
data . tweets [] . quotedTweet . entities . urls [] . expandedUrl
string required
Fully expanded destination URL.
min 1 chars
data . tweets [] . quotedTweet . entities . symbols
array required
Symbol entities.
data . tweets [] . quotedTweet . entities . symbols [] . text
string required
Cashtag or symbol text.
min 1 chars
data . tweets [] . quotedTweet . isReply
boolean required
Whether this is a reply.
data . tweets [] . quotedTweet . inReplyToTweetId
string
Parent tweet id when replying.
data . tweets [] . quotedTweet . inReplyToUserId
string
Parent author user id when replying.
data . tweets [] . quotedTweet . inReplyToScreenName
string
Parent author handle when replying.
data . tweets [] . quotedTweet . isQuote
boolean required
Whether this tweet quotes another.
data . tweets [] . quotedTweet . quotedTweetId
string
Quoted tweet id when present.
data . tweets [] . quotedTweet . isRetweet
boolean required
Whether this is a native repost.
data . tweets [] . quotedTweet . retweetedTweetId
string
Original tweet id for a repost.
data . tweets [] . quotedTweet . possiblySensitive
boolean required
Whether X marks the content sensitive.
data . tweets [] . quotedTweet . editInfo
object
Edit metadata when applicable.
data . tweets [] . quotedTweet . editInfo . editTweetIds
array required
Tweet ids in this edit chain.
data . tweets [] . quotedTweet . editInfo . editTweetIds []
string
min 1 chars
data . tweets [] . quotedTweet . editInfo . editableUntilMsec
string required
Epoch milliseconds until edits are locked.
data . tweets [] . quotedTweet . editInfo . isEditEligible
boolean required
Whether the tweet can still be edited.
data . tweets [] . quotedTweet . editInfo . editsRemaining
string required
Remaining edits in the window, as reported by X.
data . tweets [] . quotedTweet . source
string
Client label text (for example “Twitter for iPhone”).
data . tweets [] . quotedTweet . sourceUrl
string
Link target from the source anchor when present.
data . tweets [] . retweetedTweet
object
Expanded reposted tweet (one level deep).
data . tweets [] . retweetedTweet . id
string required
Tweet id (`rest_id`).
min 1 chars
data . tweets [] . retweetedTweet . url
string required
Canonical public URL for this tweet on x.com.
min 1 chars
data . tweets [] . retweetedTweet . conversationId
string required
Conversation root tweet id.
min 1 chars
data . tweets [] . retweetedTweet . createdAt
integer required
Creation time as Unix epoch seconds.
≥ 0
data . tweets [] . retweetedTweet . language
string required
BCP 47 or X language code.
min 1 chars
data . tweets [] . retweetedTweet . text
string required
Full tweet text (includes long-form when available).
data . tweets [] . retweetedTweet . isLongForm
boolean required
True when text was taken from note_tweet metadata instead of legacy.full_text alone.
data . tweets [] . retweetedTweet . displayTextRange
array required
Start/end character indices for visible text.
data . tweets [] . retweetedTweet . displayTextRange []
integer
≥ 0
data . tweets [] . retweetedTweet . author
object required nullable
Author snapshot; null when `trim=true` omits per-tweet author data.
data . tweets [] . retweetedTweet . author . handle
string required
Author screen name without the leading @.
min 1 chars
data . tweets [] . retweetedTweet . author . displayName
string required nullable
Author display name.
data . tweets [] . retweetedTweet . author . avatarUrl
string required nullable
Best available square avatar URL for the author.
data . tweets [] . retweetedTweet . author . verified
boolean required
Whether X marks the author with legacy verification.
data . tweets [] . retweetedTweet . author . blueVerified
boolean required
Whether the author has X blue (paid) verification.
data . tweets [] . retweetedTweet . author . platformUserId
string
Numeric X user id for the author as a string.
data . tweets [] . retweetedTweet . metrics
object required
Engagement metrics for a tweet.
data . tweets [] . retweetedTweet . metrics . views
integer required
Impression count when reported by X.
≥ 0
data . tweets [] . retweetedTweet . metrics . favorites
integer required
Favorite (like) count.
≥ 0
data . tweets [] . retweetedTweet . metrics . retweets
integer required
Native repost count.
≥ 0
data . tweets [] . retweetedTweet . metrics . replies
integer required
Reply count.
≥ 0
data . tweets [] . retweetedTweet . metrics . bookmarks
integer required
Bookmark count.
≥ 0
data . tweets [] . retweetedTweet . metrics . quotes
integer required
Quote tweet count.
≥ 0
data . tweets [] . retweetedTweet . media
array required
Photo, video, or GIF attachments.
data . tweets [] . retweetedTweet . media []
data . tweets [] . retweetedTweet . entities
object required
Entities aligned with `text`.
data . tweets [] . retweetedTweet . entities . hashtags
array required
Hashtag entities.
data . tweets [] . retweetedTweet . entities . hashtags [] . text
string required
Hashtag text without #.
data . tweets [] . retweetedTweet . entities . userMentions
array required
User mention entities.
data . tweets [] . retweetedTweet . entities . userMentions [] . handle
string required
Mentioned screen name.
min 1 chars
data . tweets [] . retweetedTweet . entities . userMentions [] . displayName
string
Display name when available.
data . tweets [] . retweetedTweet . entities . userMentions [] . platformUserId
string
Numeric user id for the mention when available.
data . tweets [] . retweetedTweet . entities . urls
array required
URL entities.
data . tweets [] . retweetedTweet . entities . urls [] . url
string required
Short URL as it appears in text.
min 1 chars
data . tweets [] . retweetedTweet . entities . urls [] . displayUrl
string required
Human-readable display host/path.
min 1 chars
data . tweets [] . retweetedTweet . entities . urls [] . expandedUrl
string required
Fully expanded destination URL.
min 1 chars
data . tweets [] . retweetedTweet . entities . symbols
array required
Symbol entities.
data . tweets [] . retweetedTweet . entities . symbols [] . text
string required
Cashtag or symbol text.
min 1 chars
data . tweets [] . retweetedTweet . isReply
boolean required
Whether this is a reply.
data . tweets [] . retweetedTweet . inReplyToTweetId
string
Parent tweet id when replying.
data . tweets [] . retweetedTweet . inReplyToUserId
string
Parent author user id when replying.
data . tweets [] . retweetedTweet . inReplyToScreenName
string
Parent author handle when replying.
data . tweets [] . retweetedTweet . isQuote
boolean required
Whether this tweet quotes another.
data . tweets [] . retweetedTweet . quotedTweetId
string
Quoted tweet id when present.
data . tweets [] . retweetedTweet . isRetweet
boolean required
Whether this is a native repost.
data . tweets [] . retweetedTweet . retweetedTweetId
string
Original tweet id for a repost.
data . tweets [] . retweetedTweet . possiblySensitive
boolean required
Whether X marks the content sensitive.
data . tweets [] . retweetedTweet . editInfo
object
Edit metadata when applicable.
data . tweets [] . retweetedTweet . editInfo . editTweetIds
array required
Tweet ids in this edit chain.
data . tweets [] . retweetedTweet . editInfo . editTweetIds []
string
min 1 chars
data . tweets [] . retweetedTweet . editInfo . editableUntilMsec
string required
Epoch milliseconds until edits are locked.
data . tweets [] . retweetedTweet . editInfo . isEditEligible
boolean required
Whether the tweet can still be edited.
data . tweets [] . retweetedTweet . editInfo . editsRemaining
string required
Remaining edits in the window, as reported by X.
data . tweets [] . retweetedTweet . source
string
Client label text (for example “Twitter for iPhone”).
data . tweets [] . retweetedTweet . sourceUrl
string
Link target from the source anchor when present.
Metadata describing the request and billing outcome.
meta . requestId
string required
Unique request identifier for tracing this API call.
min 1 chars
meta . creditsCharged
integer required
Credits charged for this request.
≥ 0
meta . version
string required
Public API version that served the response.
one of: v1
Code example cURL Node.js TypeScript SDK Python Go Java
Responses 200 400 401 402 500 502 503
Tweets for the requested profile. Use `data.lookupStatus`: `not_found` when the handle cannot be resolved; `found` when the handle resolves (check `data.tweets`—it may be empty when there are no popular public tweets in this response). Prefer `GET /v1/twitter/profiles/{handle}` first if you need explicit `private` vs `not_found` for the account before interpreting an empty tweet list.
Error codes
bad_request insufficient_credits internal_error lookup_failed temporarily_unavailable unauthorized