Tweet object

Interested in learning more about how the Native Enriched data format maps to the X API v2 format?

Check out our comparison guide: Native Enriched compared to X API v2

Post Object

When using enterprise data products, you will notice that much of the data dictionary is similar to the native format of Post data, with some additional enriched metadata.  The base level of the native enriched format uses much of the same object names as the X API v1.1 data format.  The Post object has a long list of ‘root-level’ attributes, including fundamental attributes such as id, created_at, and text. Post objects will also have nested objects to include the user, entities, and extended_entities. Post objects will also have other nested Post objects such as retweeted_status, quoted_status and extended_tweet.  The native enriched format will additionally have a matching_rules object.

 

X Data Dictionary

Below you will find the data dictionary for these ‘root-level’ attributes, as well as links to child object data dictionaries.

Attribute Type Description
created_at String

UTC time when this Post was created. Example:

"created_at": "Wed Oct 10 20:19:24 +0000 2018"
id Int64

The integer representation of the unique identifier for this Post. This number is greater than 53 bits and some programming languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe. Use id_str to fetch the identifier to be safe. See X IDs for more information. Example:

"id":1050118621198921728
id_str String

The string representation of the unique identifier for this Post. Implementations should use this rather than the large integer in id. Example:

"id_str":"1050118621198921728"
text String

The actual UTF-8 text of the status update. See X-text for details on what characters are currently considered valid. Example:

"text":"To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm"
source String

Utility used to post the Post, as an HTML-formatted string. Posts from the X website have a source value of web.

Example:

"source":"Twitter Web Client"
truncated Boolean

Indicates whether the value of the text parameter was truncated, for example, as a result of a retweet exceeding the original Post text length limit of 140 characters. Truncated text will end in ellipsis, like this ... Since X now rejects long Posts vs truncating them, the large majority of Posts will have this set to false . Note that while native retweets may have their toplevel text property shortened, the original text will be available under the retweeted_status object and the truncated parameter will be set to the value of the original status (in most cases, false ). Example:

"truncated":true
in_reply_to_status_id Int64

Nullable. If the represented Post is a reply, this field will contain the integer representation of the original Post's ID. Example:

"in_reply_to_status_id":1051222721923756032
in_reply_to_status_id_str String

Nullable. If the represented Post is a reply, this field will contain the string representation of the original Post's ID. Example:

"in_reply_to_status_id_str":"1051222721923756032"
in_reply_to_user_id Int64

Nullable. If the represented Post is a reply, this field will contain the integer representation of the original Post's author ID. This will not necessarily always be the user directly mentioned in the Post. Example:

"in_reply_to_user_id":6253282
in_reply_to_user_id_str String

Nullable. If the represented Post is a reply, this field will contain the string representation of the original Post's author ID. This will not necessarily always be the user directly mentioned in the Post. Example:

"in_reply_to_user_id_str":"6253282"
in_reply_to_screen_name String

Nullable. If the represented Post is a reply, this field will contain the screen name of the original Post's author. Example:

"in_reply_to_screen_name":"twitterapi"
user User object

The user who posted this Post. See User data dictionary for complete list of attributes.

Example highlighting select attributes:


 { "user": {
    "id": 6253282,
    "id_str": "6253282",
    "name": "Twitter API",
    "screen_name": "TwitterAPI",
    "location": "San Francisco, CA",
    "url": "https://developer.twitter.com",
    "description": "The Real Twitter API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.",
    "verified": true,
    "followers_count": 6129794,
    "friends_count": 12,
    "listed_count": 12899,
    "favourites_count": 31,
    "statuses_count": 3658,
    "created_at": "Wed May 23 06:01:13 +0000 2007",
    "utc_offset": null,
    "time_zone": null,
    "geo_enabled": false,
    "lang": "en",
    "contributors_enabled": false,
    "is_translator": false,
    "profile_background_color": "null",
    "profile_background_image_url": "null",
    "profile_background_image_url_https": "null",
    "profile_background_tile": null,
    "profile_link_color": "null",
    "profile_sidebar_border_color": "null",
    "profile_sidebar_fill_color": "null",
    "profile_text_color": "null",
    "profile_use_background_image": null,
    "profile_image_url": "null",
    "profile_image_url_https": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg",
    "profile_banner_url": "https://pbs.twimg.com/profile_banners/6253282/1497491515",
    "default_profile": false,
    "default_profile_image": false,
    "following": null,
    "follow_request_sent": null,
    "notifications": null
  }
}
coordinates Coordinates

Nullable. Represents the geographic location of this Post as reported by the user or client application. The inner coordinates array is formatted as geoJSON (longitude first, then latitude). Example:

"coordinates":
{
    "coordinates":
    [
        -75.14310264,
        40.05701649
    ],
    "type":"Point"
}
place Places

Nullable When present, indicates that the Post is associated (but not necessarily originating from) a Place  Example:

"place":
{
  "attributes":{},
   "bounding_box":
  {
     "coordinates":
     [[
           [-77.119759,38.791645],
           [-76.909393,38.791645],
           [-76.909393,38.995548],
           [-77.119759,38.995548]
     ]],
     "type":"Polygon"
  },
   "country":"United States",
   "country_code":"US",
   "full_name":"Washington, DC",
   "id":"01fbe706f872cb32",
   "name":"Washington",
   "place_type":"city",
   "url":"http://api.x.com/1/geo/id/0172cb32.json"
}
quoted_status_id Int64

This field only surfaces when the Post is a quote Tweet. This field contains the integer value Post ID of the quoted Tweet. Example:

"quoted_status_id":1050119905717055488
quoted_status_id_str String

This field only surfaces when the Post is a quote Tweet. This is the string representation Post ID of the quoted Tweet. Example:

"quoted_status_id_str":"1050119905717055488"
is_quote_status Boolean

Indicates whether this is a Quoted Tweet. Example:

"is_quote_status":false
quoted_status Post This field only surfaces when the Post is a quote Tweet. This attribute contains the Post object of the original Post that was quoted.
retweeted_status Post Users can amplify the broadcast of Posts authored by other users by Retweeting . Retweets can be distinguished from typical Posts by the existence of a retweeted_status attribute. This attribute contains a representation of the original Post that was retweeted. Note that retweets of retweets do not show representations of the intermediary retweet, but only the original Post. (Users can also unretweet a retweet they created by deleting their retweet.)
quote_count Integer

Nullable. Indicates approximately how many times this Post has been quoted by X users. Example:

"quote_count":33

Note: This object is only available with the Premium and Enterprise tier products.

reply_count Int

Number of times this Post has been replied to. Example:

"reply_count":30

Note: This object is only available with the Premium and Enterprise tier products.

retweet_count Int

Number of times this Post has been retweeted. Example:

"retweet_count":160
favorite_count Integer

Nullable. Indicates approximately how many times this Post has been liked by X users. Example:

"favorite_count":295
entities Entities

Entities which have been parsed out of the text of the Post. Additionally see Entities in X Objects . Example:

"entities":
{
    "hashtags":[],
    "urls":[],
    "user_mentions":[],
    "media":[],
    "symbols":[]
    "polls":[]
}
extended_entities Extended Entities

When between one and four native photos or one video or one animated GIF are in Post, contains an array 'media' metadata. This is also available in Quote Tweets. Additionally see Entities in X Objects . Example:

"entities":
{
    "media":[]
}
favorited Boolean

Nullable. Indicates whether this Post has been liked by the authenticating user. Example:

"favorited":true
retweeted Boolean

Indicates whether this Post has been Retweeted by the authenticating user. Example:

"retweeted":false
possibly_sensitive Boolean

Nullable. This field indicates content may be recognized as sensitive. The Post author can select within their own account preferences and choose “Mark media you post as having material that may be sensitive” so each Post created after has this flag set.

This may also be judged and labeled by an internal X support agent.

"possibly_sensitive":false
filter_level String

Indicates the maximum value of the filter_level parameter which may be used and still stream this Post. So a value of medium will be streamed on none, low, and medium streams.

Example:

"filter_level": "low"
lang String

Nullable. When present, indicates a BCP 47 language identifier corresponding to the machine-detected language of the Post text, or und if no language could be detected. 

 Example:

"lang": "en"
edit_history Object

Unique identifiers indicating all versions of a Post. For Posts with no edits, there will be one ID. For Posts with an edit history, there will be multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. 

The Post IDs can be used to hydrate and view previous versions of a Post.

 

Example:

edit_history": {
    "initial_tweet_id": "1283764123"
    "edit_tweet_ids": ["1283764123", "1394263866"]
  }
edit_controls Object

When present, indicates how long a Post is still editable for and the number of remaining edits. Posts are only editable for the first 30 minutes after creation and can be edited up to five times. 

The Post IDs can be used to hydrate and view previous versions of a Post.

 

Example:

"edit_controls": {  
     "editable_until_ms": 123
     "edits_remaining": 3   
  }
editable Boolean

When present, indicates if a Post was eligible for edit when published. This field is not dynamic and won't toggle from True to False when a Post reaches its editable time limit, or maximum number of edits. The following Post features will cause this field to be false:

  • Posts is promoted
  • Post has a poll
  • Post is a non-self-thread reply
  • Post is a retweet (note that Quote Tweets are eligible for edit)
  • Post is nullcast
  • Community Post
  • Superfollow Post
  • Collaborative Post

 

matching_rules Array of Rule Objects

Present in filtered products such as X Search and PowerTrack. Provides the id and tag associated with the rule that matched the Post. More on matching rules here. With PowerTrack, more than one rule can match a Post. 

Example:

"matching_rules": " [{
        "tag": "twitterapi emojis",
        "id": 1050118621198921728,
        "id_str": "1050118621198921728"
    }]"
     

 

Additional Post attributes

X APIs that provide Posts (e.g. the GET statuses/lookup endpoint) may include these additional Post attributes:

Attribute Type Description
current_user_retweet Object

Perspectival Only surfaces on methods supporting the include_my_retweet parameter, when set to true. Details the Post ID of the user’s own retweet (if existent) of this Post. Example:

"current_user_retweet": {
  "id": 6253282,
  "id_str": "6253282"
}
scopes Object

A set of key-value pairs indicating the intended contextual delivery of the containing Post. Currently used by X's Promoted Products. Example:

"scopes":{"followers":false}
withheld_copyright Boolean

When present and set to “true”, it indicates that this piece of content has been withheld due to a DMCA complaint . Example:

"withheld_copyright": true
withheld_in_countries Array of String

When present, indicates a list of uppercase two-letter country codes this content is withheld from. X supports the following non-country values for this field:

“XX” - Content is withheld in all countries “XY” - Content is withheld due to a DMCA request.

Example:

"withheld_in_countries": ["GR", "HK", "MY"]
withheld_scope String

When present, indicates whether the content being withheld is the “status” or a “user.”

Example:

"withheld_scope": "status"

 

Deprecated Attributes

Field Type Description
geo Object Deprecated. Nullable. Use the coordinates field instead. This deprecated attribute has its coordinates formatted as [lat, long], while all other Post geo is formatted as [long, lat].

 


Nested Post objects

In several cases, a Post object will included other nested objects.  If you are working with nested objects, then that JSON payload will contain multiple Post objects, and each Post object may contain its own objects. The root-level object will contain information on the type of action taken, i.e. whether it is a Retweet or a Quote Tweet, and may also contain an object that describes the 'original' Post being shared. Extended Posts will include a nested extended object that extends beyond 140 characters, which was used to prevent breaking changes when the update was made in 2017. Each nested object dictionary is described below.

 

Retweets

Retweets always contain two Post objects. The 'original' Post being Retweeted is provided in a "retweeted_status" object. The root-level object encapsulates the Retweet itself, including a User object for the account taking the Retweet action and the time of the Retweet. Retweeting is an action to share a Post with your followers, and no other new content can be added. Also, a (new) location cannot be provided with a Retweet. While the 'original' Post may have geo-tagged, the Retweet "geo" and "place" objects will always be null.

Even before the introduction of Extended Posts, the root-level "entities" object was in some cases truncated and incomplete due to the "RT @username " string being appended to Post message being Retweeted.  Note that if a Retweet gets Retweeted, the "retweet_status" will still point to the original Post, meaning the intermediate Retweet is not included. Similar behavior is seen when using x.com to 'display' a Retweet. If you copy the unique Post ID assigned to the Retweet 'action', the original Post is displayed. 

Below is an example structure for a Retweet. Again, when parsing Retweets, it is key to parse the "retweeted_status" object for complete (original) Post message and entity metadata.

      {
	"tweet": {
		"text": "RT @author original message",
		"user": {
			"screen_name": "Retweeter"
		},
		"retweeted_status": {
			"text": "original message",
			"user": {
				"screen_name": "OriginalTweeter"
			},
			"place": {},
			"entities": {},
			"extended_entities": {}
		}
	},
	"entities": {},
	"extended_entities": {}
}
    

 

Quote Tweets

Quote Tweets are much like Retweets except that they include a new Post message. These new messages can contain their own set of hashtags, links, and other "entities" metadata. Quote Tweets can also include location information shared by the user posting the Quote Tweet, along with media such as GIFs, videos, and photos.

Quote Tweets will contain at least two Post objects, and in some cases, three. The Post being Quoted, which itself can be a Quoted Tweet, is provided in a "quoted_status" object. The root-level object encapsulates the Quote Tweet itself, including a User object for the account taking the sharing action and the time of the Quote Tweet.

Note that Quote Tweets can now have photos, GIFs, or videos, added to them using the 'Post' user-interface. When links to externally hosted media are included in the Quote Tweet message, the root-level "entities.urls" will describe those. Media attached to Quote Tweets will appear in the root-level "extended_entities" metadata.

When Quote Tweets were first launched, a shortened link (t.co URL) was appended to the 'original' Post message and provided in the root-level "text" field. In addition, metadata for that t.co URL was included in the root-level 'entities.urls' array. In May 2018, we changed this so that the shortened t.co URL to the quoted Tweet will not be included in the root-level "text" field. Second, the metadata for the quoted Tweet will not be included in the "entities.urls" metadata. Instead, URL metadata for the quoted Tweet will be in a new "quoted_status_permalink" object on the root-level (or top-level), so at the same level of the "quoted_status" object.

Below is an example structure for a Quote Tweet using this original formatting. 

      {
	"created_at": "Tue Feb 14 19:30:06 +0000 2017",
	"id_str": "831586333415976960",
	"text": "Definitely quotable! https:\/\/t.co\/J1LKrbHpWR",
	"user": {
		"screen_name": "happycamper"
	},
	"quoted_status_id_str": "831569219296882688",
	"quoted_status": {
		"created_at": "Tue Feb 14 18:22:06 +0000 2017",
		"id_str": "831569219296882688",
		"text": "This is a test of the tweeting system \ud83d\ude0e to update #supportdocs @twitterboulder here: https:\/\/t.co\/NRq9UrSzm0",
		"user": {
			"screen_name": "furiouscamper",
		},
		"place": {
			"id": "9a974dfc8efb32a0",
		},
		"entities": {
			"hashtags": [{
				"text": "supportdocs",
			}],
			"urls": [{
			}],
			"user_mentions": [{	}],
			"symbols": []
		},
	},
	"is_quote_status": true,
	"entities": {},
	"matching_rules": [{}]
}
    
      {
	"created_at": "Fri Jan 04 18:47:16 +0000 2019",
	"id_str": "1081260794069671936",
	"text": "Quote test https://t.co/CE4m1qs3NJ",
	"user": {
		"screen_name": "furiouscamper"
	},
	"place": null,
	"quoted_status_id_str": "1079578364904648705",
	"quoted_status": {
		"created_at": "Mon Dec 31 03:21:54 +0000 2018",
		"id_str": "1079578364904648705",
		"text": "AHHHHH",
		"user": {
			"screen_name": "infinite_scream"
		},
		"place": null,
		"is_quote_status": false,
		"quote_count": 1,
		"reply_count": 0,
		"retweet_count": 3,
		"favorite_count": 6,
		"entities": {
			"hashtags": [],
			"urls": [],
			"user_mentions": [],
			"symbols": []
		}
	},
	"quoted_status_permalink": {
		"url": "https://t.co/CE4m1qs3NJ",
		"expanded": "https://twitter.com/infinite_scream/status/1079578364904648705",
		"display": "twitter.com/infinite_screa…"
	},
	"is_quote_status": true,
	"quote_count": 0,
	"reply_count": 0,
	"retweet_count": 0,
	"favorite_count": 1,
	"entities": {}
}
    

 

Extended Posts

JSON that describes Extended Posts was introduced when 280-character Posts were launched in November 2017. Post JSON was extended to encapsulate these longer messages, while not breaking the thousands of apps parsing these fundamental X objects. To provide full backward compatibility, the original 140-character 'text' field, and the entity objects parsed from that, were retained. In the case of Posts longer than 140 characters, this root-level 'text' field would become truncated and thus incomplete. Since the root-level 'entities' objects contain arrays of key metadata parsed from the 'text' message, such as included hashtags and links, these collections would be incomplete. For example, if a Post message was 200 characters long, with a hashtag included at the end, the legacy root-level 'entities.hashtags' array would not include it. 

A new 'extended_tweet' field was introduced to hold the longer Post messages and complete entity metadata. The "extended_tweet" object provides the "full_text" field that contains the complete, untruncated Post message when longer than 140 characters. The "extended_tweet" object also contains an "entities" object with complete arrays of hashtags, links, mentions, etc.

Extended Posts are identified with a root-level "truncated" boolean. When true ("truncated": true), the "extended_tweet" fields should be parsed instead of the root-level fields.

Note in the JSON example below that the root-level "text" field is truncated and the root-level "entities.hashtags" array is empty even though the Post message includes three hashtags. Since this is an Extended Post, the "truncated" field is set to true, and the "extended_tweet" object provides complete "full_text" and "entities" Post metadata.

      {
	"created_at": "Thu May 10 17:41:57 +0000 2018",
	"id_str": "994633657141813248",
	"text": "Just another Extended Tweet with more than 140 characters, generated as a documentation example, showing that [\"tru… https://t.co/U7Se4NM7Eu",
	"display_text_range": [0, 140],
	"truncated": true,
	"user": {
		"id_str": "944480690",
		"screen_name": "FloodSocial"
	},
	"extended_tweet": {
		"full_text": "Just another Extended Tweet with more than 140 characters, generated as a documentation example, showing that [\"truncated\": true] and the presence of an \"extended_tweet\" object with complete text and \"entities\" #documentation #parsingJSON #GeoTagged https://t.co/e9yhQTJSIA",
		"display_text_range": [0, 249],
		"entities": {
			"hashtags": [{
				"text": "documentation",
				"indices": [211, 225]
			}, {
				"text": "parsingJSON",
				"indices": [226, 238]
			}, {
				"text": "GeoTagged",
				"indices": [239, 249]
			}]
		}

	},
	"entities": {
		"hashtags": []
	}
}