Skip to content

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.

FieldWhat it holds
textReadable 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.
fullTextThe 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.
displayTextRangeThe 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.
noteTweetThe 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]
      }
    ]
  }
}
ListFields of each item
urlsurl (the t.co link), expandedUrl, displayUrl, indices
userMentionsid, username, name, indices
hashtagstext (without the # sign), indices
symbolstext (the cashtag without the $ sign), indices
mediaid, 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:

FieldWhat it holds
idX's ID of the note.
textThe whole text as X sends it, with its t.co links.
entitiesurls, userMentions, hashtags and symbols, positioned in this text, not in fullText.
richtextTagsBold and italic spans: fromIndex, toIndex and types (for example ["Bold"]).
inlineMediaAttachments placed inside the text: mediaId and index.
isExpandableWhether 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.

FieldWhat it holds
nameX's name for the card, for example summary_large_image, player or 745291183405076480:broadcast.
cardTypeThe name without its numeric prefix, for example broadcast.
typeA simplified type: summary, player, app, promo, broadcast, live, event and similar.
urlThe t.co link of the card.
bindingValuesA short summary: title, description, domain, thumbnailImageUrl, thumbnailImageColor, playerUrl, playerWidth, playerHeight, appId, appName, appStarRating, appPriceAmount, appPriceCurrency. Fields that do not apply are null or empty.
rawBindingValuesEvery value X sent for the card, by X's key, with its type. See below.
vanityUrlThe domain X shows on the card, or null.
userRefsResultsThe accounts the card refers to, as user objects, or null.
imageUrl, videoUrl, playerUrlShortcuts to the main image, video and player link, when the card has them.
cardPlatformThe 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:

typeFieldContent
STRINGstring_valueText. Numbers such as a video width also come as text.
IMAGEimage_valueurl, width, height and alt.
BOOLEANboolean_valuetrue or false.
IMAGE_COLORimage_color_valueThe colour palette of an image.
USERuser_valueid_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.

FieldWhat it holds
idX's ID of the place.
nameShort name, for example "Manhattan".
fullNameFull name, for example "Manhattan, NY".
country, countryCodeCountry name and two-letter code.
placeTypeFor example city, admin, country or poi.
urlX's link for the place.
boundingBoxtype (Polygon) and coordinates, the corners of the area as X sends them.
centroid, polylines, containedWithin, attributesAlways null or empty.

Edits, pins and reply limits

FieldWhat it holds
editControleditTweetIds (the ID of every version), editableUntil, isEditEligible, editsRemaining, and initialTweetId, set on a later version of an edited tweet.
isEditedtrue when the tweet has more than one version.
isPinnedtrue when the tweet is pinned on its author's profile.
conversationControlSet when the author limited who can reply. policy says how, for example Community or ByInvitation.
limitedActionsThe actions X limits on the tweet, as comma-separated text, for example "Reply". null when there are none.
isLimitedReplytrue 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:

FieldInside a tweet
listedCount0, whatever the real count is.
hasCustomTimelinesfalse, whatever the real value is.
fastFollowersCount, canDm, wantRetweetsnull.
verifiedSince, isIdentityVerifiednull and false.
canMediaTagThe 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.