Returns public metadata and engagement for a single tweet on X, including author profile context and an expanded quoted tweet when present.
GET /v1/twitter/tweets
Headers x-api-key string required (header)
API key (`sfk_...`)
Parameters url string required (query)
Tweet permalink or identifier.
min 1 chars · max 4096 chars
trim boolean (query)
Optional: omit author profile and tweet `core` for a smaller response.
Response fields Endpoint-specific response payload.
data . lookupStatus
string required
Whether the tweet was found or unavailable.
one of: found, not_found
data . author
object required nullable
Author profile and metrics when not trimmed; null when `trim=true` or when not found.
data . author . profile
object required
Profile fields for the tweet author.
data . author . profile . platform
string required
Social platform for this profile.
one of: twitter
data . author . profile . handle
string required
X screen name (handle) without the leading @.
data . author . profile . displayName
string required nullable
Display name shown on the profile.
data . author . profile . bio
string required nullable
Profile biography text.
data . author . profile . avatarUrl
string required nullable
Best available square avatar image URL.
data . author . profile . bannerUrl
string nullable
Profile banner image URL when available.
data . author . profile . verified
boolean required
Whether X marks the profile with legacy verification (not necessarily paid blue).
data . author . profile . blueVerified
boolean required
Whether the account has X blue (paid) verification.
data . author . profile . profileUrl
string required
Canonical public profile URL on x.com.
min 1 chars
data . author . profile . privateAccount
boolean required
Whether the account is protected (private).
data . author . profile . platformUserId
string
Numeric X user id (`rest_id`) as a string.
data . author . profile . accountCreatedAt
integer
Account creation time as Unix epoch seconds when derivable.
≥ 0
data . author . profile . location
string nullable
Location string from the profile when provided.
data . author . profile . website
string nullable
Primary outbound link (expanded URL) from the profile.
data . author . profile . pinnedTweetId
string
Pinned tweet id when X exposes one.
data . author . profile . verificationInfo
object
Structured verification metadata from X.
data . author . profile . verificationInfo . isIdentityVerified
boolean required
Whether X marks the account as identity-verified.
data . author . profile . verificationInfo . verifiedSinceMsec
string
When verification became effective, as milliseconds since epoch (string from X).
data . author . profile . verificationInfo . reason
object
Verification reason payload when X provides it.
data . author . profile . verificationInfo . reason . text
string
Human-readable verification reason text from X.
data . author . profile . verificationInfo . reason . entities
array
Inline entity metadata for the reason text (vendor-defined).
data . author . profile . verificationInfo . reason . entities []
nullable
data . author . profile . tipJar
object
Tip jar configuration when present.
data . author . profile . tipJar . isEnabled
boolean required
Whether the X tip jar is enabled.
data . author . profile . tipJar . handles
object
Per-service handles when any are present.
data . author . profile . tipJar . handles . bandcamp
string
Bandcamp handle from tip jar.
data . author . profile . tipJar . handles . bitcoin
string
Bitcoin address or handle.
data . author . profile . tipJar . handles . cashApp
string
Cash App handle.
data . author . profile . tipJar . handles . ethereum
string
Ethereum address or handle.
data . author . profile . tipJar . handles . goFundMe
string
GoFundMe handle.
data . author . profile . tipJar . handles . patreon
string
Patreon handle.
data . author . profile . tipJar . handles . payPal
string
PayPal handle.
data . author . profile . tipJar . handles . venmo
string
Venmo handle.
data . author . profile . highlights
object
Tweet highlights metadata when present.
data . author . profile . highlights . canHighlightTweets
boolean required
Whether the account may highlight tweets on the profile.
data . author . profile . highlights . highlightedTweetCount
integer required
Count of highlighted tweets when reported by X.
≥ 0
data . author . profile . businessAccount
object
Opaque business-account payload from X when non-empty (vendor-defined).
data . author . profile . creatorSubscriptionsCount
integer
Creator subscriptions count when X reports it.
≥ 0
data . author . profile . affiliateLabel
object
Affiliate or business label when X provides one.
data . author . profile . affiliateLabel . description
string required
Affiliate or business label text shown on the profile.
data . author . profile . affiliateLabel . badgeUrl
string
Badge image URL when X provides one.
data . author . profile . affiliateLabel . url
string
Destination URL for the label link.
data . author . metrics
object required
Aggregate counts for the tweet author.
data . author . metrics . followers
integer required
Follower count from X.
≥ 0
data . author . metrics . following
integer required
Following (friends) count from X.
≥ 0
data . author . metrics . tweets
integer required
Total post (status) count from X.
≥ 0
data . author . metrics . favourites
integer required
Total favourites (likes) count from X.
≥ 0
data . author . metrics . listedCount
integer
Listed count when X provides it.
≥ 0
data . author . metrics . mediaCount
integer
Media item count when X provides it.
≥ 0
data . author . metrics . fastFollowersCount
integer
Fast-followers count when X provides it.
≥ 0
data . tweet
object required nullable
Tweet body, metrics, and optional quoted tweet; null when not found.
data . tweet . id
string required
Tweet id (`rest_id`).
min 1 chars
data . tweet . url
string required
Canonical public URL for this tweet on x.com.
min 1 chars
data . tweet . conversationId
string required
Conversation root tweet id.
min 1 chars
data . tweet . createdAt
integer required
Creation time as Unix epoch seconds.
≥ 0
data . tweet . language
string required
BCP 47 or X language code.
min 1 chars
data . tweet . text
string required
Full tweet text (includes long-form when available).
data . tweet . isLongForm
boolean required
True when text was taken from note_tweet metadata instead of legacy.full_text alone.
data . tweet . displayTextRange
array required
Start/end character indices for visible text.
data . tweet . displayTextRange []
integer
≥ 0
data . tweet . metrics
object required
Engagement metrics for a tweet.
data . tweet . metrics . views
integer required
Impression count when reported by X.
≥ 0
data . tweet . metrics . favorites
integer required
Favorite (like) count.
≥ 0
data . tweet . metrics . retweets
integer required
Native repost count.
≥ 0
data . tweet . metrics . replies
integer required
Reply count.
≥ 0
data . tweet . metrics . bookmarks
integer required
Bookmark count.
≥ 0
data . tweet . metrics . quotes
integer required
Quote tweet count.
≥ 0
data . tweet . media
array required
Photo, video, or GIF attachments.
data . tweet . entities
object required
Entities aligned with `text`.
data . tweet . entities . hashtags
array required
Hashtag entities.
data . tweet . entities . hashtags [] . text
string required
Hashtag text without #.
data . tweet . entities . userMentions
array required
User mention entities.
data . tweet . entities . userMentions [] . handle
string required
Mentioned screen name.
min 1 chars
data . tweet . entities . userMentions [] . displayName
string
Display name when available.
data . tweet . entities . userMentions [] . platformUserId
string
Numeric user id for the mention when available.
data . tweet . entities . urls
array required
URL entities.
data . tweet . entities . urls [] . url
string required
Short URL as it appears in text.
min 1 chars
data . tweet . entities . urls [] . displayUrl
string required
Human-readable display host/path.
min 1 chars
data . tweet . entities . urls [] . expandedUrl
string required
Fully expanded destination URL.
min 1 chars
data . tweet . entities . symbols
array required
Symbol entities.
data . tweet . entities . symbols [] . text
string required
Cashtag or symbol text.
min 1 chars
data . tweet . isReply
boolean required
Whether this is a reply.
data . tweet . inReplyToTweetId
string
Parent tweet id when replying.
data . tweet . inReplyToUserId
string
Parent author user id when replying.
data . tweet . inReplyToScreenName
string
Parent author handle when replying.
data . tweet . isQuote
boolean required
Whether this tweet quotes another.
data . tweet . quotedTweetId
string
Quoted tweet id when present.
data . tweet . isRetweet
boolean required
Whether this is a native repost.
data . tweet . retweetedTweetId
string
Original tweet id for a repost.
data . tweet . possiblySensitive
boolean required
Whether X marks the content sensitive.
data . tweet . editInfo
object
Edit metadata when applicable.
data . tweet . editInfo . editTweetIds
array required
Tweet ids in this edit chain.
data . tweet . editInfo . editTweetIds []
string
min 1 chars
data . tweet . editInfo . editableUntilMsec
string required
Epoch milliseconds until edits are locked.
data . tweet . editInfo . isEditEligible
boolean required
Whether the tweet can still be edited.
data . tweet . editInfo . editsRemaining
string required
Remaining edits in the window, as reported by X.
Client label text (for example “Twitter for iPhone”).
data . tweet . sourceUrl
string
Link target from the source anchor when present.
data . tweet . quotedTweet
object
Quoted tweet expanded one level (no further nesting on this field).
data . tweet . quotedTweet . id
string required
Tweet id (`rest_id`).
min 1 chars
data . tweet . quotedTweet . url
string required
Canonical public URL for this tweet on x.com.
min 1 chars
data . tweet . quotedTweet . conversationId
string required
Conversation root tweet id.
min 1 chars
data . tweet . quotedTweet . createdAt
integer required
Creation time as Unix epoch seconds.
≥ 0
data . tweet . quotedTweet . language
string required
BCP 47 or X language code.
min 1 chars
data . tweet . quotedTweet . text
string required
Full tweet text (includes long-form when available).
data . tweet . quotedTweet . isLongForm
boolean required
True when text was taken from note_tweet metadata instead of legacy.full_text alone.
data . tweet . quotedTweet . displayTextRange
array required
Start/end character indices for visible text.
data . tweet . quotedTweet . displayTextRange []
integer
≥ 0
data . tweet . quotedTweet . author
object required nullable
Author snapshot; null when `trim=true` omits per-tweet author data.
data . tweet . quotedTweet . author . handle
string required
Author screen name without the leading @.
min 1 chars
data . tweet . quotedTweet . author . displayName
string required nullable
Author display name.
data . tweet . quotedTweet . author . avatarUrl
string required nullable
Best available square avatar URL for the author.
data . tweet . quotedTweet . author . verified
boolean required
Whether X marks the author with legacy verification.
data . tweet . quotedTweet . author . blueVerified
boolean required
Whether the author has X blue (paid) verification.
data . tweet . quotedTweet . author . platformUserId
string
Numeric X user id for the author as a string.
data . tweet . quotedTweet . metrics
object required
Engagement metrics for a tweet.
data . tweet . quotedTweet . metrics . views
integer required
Impression count when reported by X.
≥ 0
data . tweet . quotedTweet . metrics . favorites
integer required
Favorite (like) count.
≥ 0
data . tweet . quotedTweet . metrics . retweets
integer required
Native repost count.
≥ 0
data . tweet . quotedTweet . metrics . replies
integer required
Reply count.
≥ 0
data . tweet . quotedTweet . metrics . bookmarks
integer required
Bookmark count.
≥ 0
data . tweet . quotedTweet . metrics . quotes
integer required
Quote tweet count.
≥ 0
data . tweet . quotedTweet . media
array required
Photo, video, or GIF attachments.
data . tweet . quotedTweet . media []
data . tweet . quotedTweet . entities
object required
Entities aligned with `text`.
data . tweet . quotedTweet . entities . hashtags
array required
Hashtag entities.
data . tweet . quotedTweet . entities . hashtags [] . text
string required
Hashtag text without #.
data . tweet . quotedTweet . entities . userMentions
array required
User mention entities.
data . tweet . quotedTweet . entities . userMentions [] . handle
string required
Mentioned screen name.
min 1 chars
data . tweet . quotedTweet . entities . userMentions [] . displayName
string
Display name when available.
data . tweet . quotedTweet . entities . userMentions [] . platformUserId
string
Numeric user id for the mention when available.
data . tweet . quotedTweet . entities . urls
array required
URL entities.
data . tweet . quotedTweet . entities . urls [] . url
string required
Short URL as it appears in text.
min 1 chars
data . tweet . quotedTweet . entities . urls [] . displayUrl
string required
Human-readable display host/path.
min 1 chars
data . tweet . quotedTweet . entities . urls [] . expandedUrl
string required
Fully expanded destination URL.
min 1 chars
data . tweet . quotedTweet . entities . symbols
array required
Symbol entities.
data . tweet . quotedTweet . entities . symbols [] . text
string required
Cashtag or symbol text.
min 1 chars
data . tweet . quotedTweet . isReply
boolean required
Whether this is a reply.
data . tweet . quotedTweet . inReplyToTweetId
string
Parent tweet id when replying.
data . tweet . quotedTweet . inReplyToUserId
string
Parent author user id when replying.
data . tweet . quotedTweet . inReplyToScreenName
string
Parent author handle when replying.
data . tweet . quotedTweet . isQuote
boolean required
Whether this tweet quotes another.
data . tweet . quotedTweet . quotedTweetId
string
Quoted tweet id when present.
data . tweet . quotedTweet . isRetweet
boolean required
Whether this is a native repost.
data . tweet . quotedTweet . retweetedTweetId
string
Original tweet id for a repost.
data . tweet . quotedTweet . possiblySensitive
boolean required
Whether X marks the content sensitive.
data . tweet . quotedTweet . editInfo
object
Edit metadata when applicable.
data . tweet . quotedTweet . editInfo . editTweetIds
array required
Tweet ids in this edit chain.
data . tweet . quotedTweet . editInfo . editTweetIds []
string
min 1 chars
data . tweet . quotedTweet . editInfo . editableUntilMsec
string required
Epoch milliseconds until edits are locked.
data . tweet . quotedTweet . editInfo . isEditEligible
boolean required
Whether the tweet can still be edited.
data . tweet . quotedTweet . editInfo . editsRemaining
string required
Remaining edits in the window, as reported by X.
data . tweet . quotedTweet . source
string
Client label text (for example “Twitter for iPhone”).
data . tweet . quotedTweet . 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
Tweet details when available. Check `data.lookupStatus` for `found` vs `not_found`.
Error codes
bad_request insufficient_credits internal_error lookup_failed temporarily_unavailable unauthorized