Tweet Object
Every endpoint that returns tweets returns the same tweet object: lookups, timelines, search, lists and communities. This page explains the fields that need more than their name. Each endpoint page shows a full example response.
Text
A tweet carries its text in two forms.
| Field | What it holds |
|---|---|
text | Readable text. Every t.co link is replaced by the link it points to, the media link included, and a long post is given in full. On a repost it is the original post's readable text. |
fullText | The text exactly as X sends it. It keeps the t.co links. On a repost it starts with "RT @username:" and X cuts it at about 140 characters. On a long post it holds only the first 280 characters or so. |
displayTextRange | The part of fullText X displays, as [start, end]. It leaves out the mentions at the start of a reply and the media link at the end. |
noteTweet | The whole text of a long post. null on other tweets. See Long posts. |
Use text to show or analyse a tweet. Use fullText with entities when you need X's original text and the position of every link, mention and tag in it.
Entities
entities lists what X found in fullText, each item with its position.
{
"fullText": "Launch day 🚀 with @sample_user_10001: https://t.co/AbCdEf1234 #launch $ACME https://t.co/XyZ9876543",
"displayTextRange": [0, 75],
"entities": {
"urls": [
{
"url": "https://t.co/AbCdEf1234",
"expandedUrl": "https://example.com/launch",
"displayUrl": "example.com/launch",
"indices": [38, 61]
}
],
"userMentions": [
{ "id": "1234567890", "username": "sample_user_10001", "name": "Sample User", "indices": [18, 36] }
],
"hashtags": [{ "text": "launch", "indices": [62, 69] }],
"symbols": [{ "text": "ACME", "indices": [70, 75] }],
"media": [
{
"id": "900000000000000001",
"key": "3_900000000000000001",
"type": "photo",
"url": "https://t.co/XyZ9876543",
"expandedUrl": "https://x.com/sample_user_10001/status/200000000000000001/photo/1",
"displayUrl": "pic.x.com/XyZ9876543",
"indices": [76, 99]
}
]
}
}
| List | Fields of each item |
|---|---|
urls | url (the t.co link), expandedUrl, displayUrl, indices |
userMentions | id, username, name, indices |
hashtags | text (without the # sign), indices |
symbols | text (the cashtag without the $ sign), indices |
media | id, key, type (photo, video or animated_gif), url (the t.co link), expandedUrl, displayUrl, indices |
media has one entry per attached photo, video or GIF. They all share one t.co link at the end of fullText. The files themselves are in the tweet's media array.
Positions
indices is [start, end], with the end not included. Positions count Unicode code points, as X counts them: an emoji is one position. JavaScript strings count some characters as two, so slice through Array.from:
const slice = (text, [start, end]) => Array.from(text).slice(start, end).join("");
slice(tweet.fullText, tweet.entities.urls[0].indices); // "https://t.co/AbCdEf1234"
In Python, plain slicing is correct: tweet["fullText"][start:end].
indices is null in the rare case where X sends no position for an item.
The shorter lists
The older fields stay: urls (expanded links as strings), mentions (id, username, name), hashtags and symbols (strings). They carry no positions. On a long post they describe the whole text.
Long posts
A post longer than 280 characters has noteTweet:
| Field | What it holds |
|---|---|
id | X's ID of the note. |
text | The whole text as X sends it, with its t.co links. |
entities | urls, userMentions, hashtags and symbols, positioned in this text, not in fullText. |
richtextTags | Bold and italic spans: fromIndex, toIndex and types (for example ["Bold"]). |
inlineMedia | Attachments placed inside the text: mediaId and index. |
isExpandable | Whether X marks the post as expandable. |
Card
card is the link preview, player, broadcast or app card attached to a tweet. It is null when the tweet has none, and for polls, which are in poll.
| Field | What it holds |
|---|---|
name | X's name for the card, for example summary_large_image, player or 745291183405076480:broadcast. |
cardType | The name without its numeric prefix, for example broadcast. |
type | A simplified type: summary, player, app, promo, broadcast, live, event and similar. |
url | The t.co link of the card. |
bindingValues | A short summary: title, description, domain, thumbnailImageUrl, thumbnailImageColor, playerUrl, playerWidth, playerHeight, appId, appName, appStarRating, appPriceAmount, appPriceCurrency. Fields that do not apply are null or empty. |
rawBindingValues | Every value X sent for the card, by X's key, with its type. See below. |
vanityUrl | The domain X shows on the card, or null. |
userRefsResults | The accounts the card refers to, as user objects, or null. |
imageUrl, videoUrl, playerUrl | Shortcuts to the main image, video and player link, when the card has them. |
cardPlatform | The platform X built the card for. |
Raw card values
rawBindingValues is an object keyed by X's own names. Each value says its type and holds the matching field:
type | Field | Content |
|---|---|---|
STRING | string_value | Text. Numbers such as a video width also come as text. |
IMAGE | image_value | url, width, height and alt. |
BOOLEAN | boolean_value | true or false. |
IMAGE_COLOR | image_color_value | The colour palette of an image. |
USER | user_value | id_str, the ID of an account. |
{
"name": "summary_large_image",
"cardType": "summary_large_image",
"type": "summary",
"url": "https://t.co/AbCdEf1234",
"bindingValues": {
"title": "Example launch",
"description": "What we shipped today.",
"domain": "example.com",
"thumbnailImageUrl": "https://example.com/images/launch-card.jpg"
},
"rawBindingValues": {
"title": { "type": "STRING", "string_value": "Example launch" },
"description": { "type": "STRING", "string_value": "What we shipped today." },
"domain": { "type": "STRING", "string_value": "example.com" },
"card_url": { "type": "STRING", "string_value": "https://t.co/AbCdEf1234", "scribe_key": "card_url" },
"thumbnail_image_original": {
"type": "IMAGE",
"image_value": {
"url": "https://example.com/images/launch-card.jpg",
"width": 1200,
"height": 628,
"alt": "Example launch"
}
}
}
}
The keys depend on the card. A link preview has about 26, mostly the same image in several sizes. A broadcast card has keys such as broadcast_title, broadcast_state and broadcast_thumbnail_original. A card adds 5 to 8 KB to a tweet.
Poll
poll is set on tweets with a poll, and card is null on them. It has id, options (position, label, voteCount, percentage), endDatetime, durationMinutes, votingStatus (open or closed) and totalVotes. rawBindingValues holds every value of X's poll card, in the same form as on a card.
Place
place is set when a tweet is tagged with a place, and null otherwise. It holds X's place fields under camelCase names.
| Field | What it holds |
|---|---|
id | X's ID of the place. |
name | Short name, for example "Manhattan". |
fullName | Full name, for example "Manhattan, NY". |
country, countryCode | Country name and two-letter code. |
placeType | For example city, admin, country or poi. |
url | X's link for the place. |
boundingBox | type (Polygon) and coordinates, the corners of the area as X sends them. |
centroid, polylines, containedWithin, attributes | Always null or empty. |
Edits, pins and reply limits
| Field | What it holds |
|---|---|
editControl | editTweetIds (the ID of every version), editableUntil, isEditEligible, editsRemaining, and initialTweetId, set on a later version of an edited tweet. |
isEdited | true when the tweet has more than one version. |
isPinned | true when the tweet is pinned on its author's profile. |
conversationControl | Set when the author limited who can reply. policy says how, for example Community or ByInvitation. |
limitedActions | The actions X limits on the tweet, as comma-separated text, for example "Reply". null when there are none. |
isLimitedReply | true when conversationControl is set or limitedActions includes Reply. |
Source
source is the app a tweet was sent from. X usually leaves it out, so expect null on most tweets.
Author fields inside a tweet
X sends less about an account inside a tweet than in a profile lookup. For the author of a tweet, and for users inside quoted tweets, reposts and cards:
| Field | Inside a tweet |
|---|---|
listedCount | 0, whatever the real count is. |
hasCustomTimelines | false, whatever the real value is. |
fastFollowersCount, canDm, wantRetweets | null. |
verifiedSince, isIdentityVerified | null and false. |
canMediaTag | The real value. |
Fetch the profile with By Username or By User ID when you need them. canDm, canMediaTag and wantRetweets describe what the account that fetched the data can do or see, not a setting of the profile alone.
Reposts and quotes
A repost has type: "retweet" and the original tweet in retweetedTweet. Its own urls, mentions, media and entities describe X's cut "RT @username: …" text, so read them from retweetedTweet for the complete lists. A quote has type: "quote" and the quoted tweet in quotedTweet.
Missing tweets
Tweet Details By IDs returns null in place of a tweet X has nothing to show for. That page explains when, and whether to retry.