Tweet
Tweets are the basic building block of all things Twitter. The Tweet object has a long list of ‘root-level’ fields, such as id
, text
, and created_at
. Tweet objects are also the ‘parent’ object to several child objects including user
, media
, poll
, and place
. Use the field parameter tweet.fields
when requesting these root-level fields on the Tweet object.
The Tweet object that can be found and expanded in the user resource. Additional Tweets related to the requested Tweet can also be found and expanded in the Tweet resource. The object is available for expansion with ?expansions=pinned_tweet_id
in the user resource or ?expansions=referenced_tweets.id
in the Tweet resource to get the object with only default fields. Use the expansion with the field parameter: tweet.fields
when requesting additional fields to complete the object.
Field value | Type | Description | How it can be used |
---|---|---|---|
id (default) | string | The unique identifier of the requested Tweet.
|
Use this to programmatically retrieve a specific Tweet. |
text (default) |
string |
The actual UTF-8 text of the Tweet. See twitter-text for details on what characters are currently considered valid.
|
Keyword extraction and sentiment analysis/classification. |
attachments |
object |
Specifies the type of attachments (if any) present in this Tweet.
|
Understanding the objects returned for requested expansions |
author_id |
string |
The unique identifier of the User who posted this Tweet.
|
Hydrating User object, sharing dataset for peer review |
context_annotations |
array |
Contains context annotations for the Tweet.
|
Entity recognition/extraction, topical analysis |
conversation_id |
string |
The Tweet ID of the original Tweet of the conversation (which includes direct replies, replies of replies).
|
Use this to reconstruct the conversation from a Tweet. |
created_at |
date (ISO 8601) |
Creation time of the Tweet.
|
This field can be used to understand when a Tweet was created and used for time-series analysis etc. |
entities |
object |
Entities which have been parsed out of the text of the Tweet. Additionally see entities in Twitter Objects.
|
Entities are JSON objects that provide additional information about hashtags, urls, user mentions, and cashtags associated with a Tweet. Reference each respective entity for further details. Please note that all start indices are inclusive. The majority of end indices are exclusive, except for entities.annotations.end, which is currently inclusive. We will be changing this to exclusive with our v3 bump since it is a breaking change. |
geo |
object |
Contains details about the location tagged by the user in this Tweet, if they specified one.
|
Determine if a Tweet is related to a named location with corresponding geo coordinates. |
in_reply_to_user_id |
string |
If the represented Tweet is a reply, this field will contain the original Tweet’s author ID. This will not necessarily always be the user directly mentioned in the Tweet.
|
Use this to determine if this Tweet was in reply to another Tweet. |
lang |
string |
Language of the Tweet, if detected by Twitter. Returned as a BCP47 language tag.
|
Classify Tweets by spoken language. |
non_public_metrics |
object |
Non-public engagement metrics for the Tweet at the time of the request. Requires user context authentication.
|
Use this to determine the total number of impressions generated for the Tweet. |
organic_metrics |
object |
Engagement metrics, tracked in an organic context, for the Tweet at the time of the request. Requires user context authentication.
|
Use this to measure organic engagement for the Tweet. |
possibly_sensitive |
boolean |
This field only surfaces when a Tweet contains a link. The meaning of the field doesn’t pertain to the Tweet content itself, but instead it is an indicator that the URL contained in the Tweet may contain content or media identified as sensitive content.
|
Studying circulation of certain types of content. |
promoted_metrics |
object |
Engagement metrics, tracked in a promoted context, for the Tweet at the time of the request. Requires user context authentication.
|
Use this to measure engagement for the Tweet when it was promoted. |
public_metrics |
object |
Public engagement metrics for the Tweet at the time of the request.
|
Use this to measure Tweet engagement. |
referenced_tweets |
array |
A list of Tweets this Tweet refers to. For example, if the parent Tweet is a Retweet, a Retweet with comment (also known as Quoted Tweet) or a Reply, it will include the related Tweet referenced to by its parent.
|
This field can be used to understand conversational aspects of retweets etc. |
reply_settings | string | Shows you who can reply to a given Tweet. Fields returned are "everyone", "mentioned_users", and "followers".
|
This field allows you to determine whether conversation reply settings have been set for the Tweet and if so, what settings have been set. |
source |
string |
The name of the app the user Tweeted from.
|
Determine if a Twitter user posted from the web, mobile device, or other app. |
withheld |
object |
When present, contains withholding details for withheld content.
|
Retrieving a Tweet object
Sample Request
In the following request, we are requesting fields for the Tweet on the Tweets lookup endpoint. Be sure to replace $BEARER_TOKEN
with your own generated Bearer Token.
curl --request GET 'https://api.twitter.com/2/tweets?ids=1212092628029698048&tweet.fields=attachments,author_id,context_annotations,created_at,entities,geo,id,in_reply_to_user_id,lang,possibly_sensitive,public_metrics,referenced_tweets,source,text,withheld&expansions=referenced_tweets.id' --header 'Authorization: Bearer $BEARER_TOKEN'
Sample Response
{
"data": [
{
"id": "1212092628029698048",
"text": "We believe the best future version of our API will come from building it with YOU. Here’s to another great year with everyone who builds on the Twitter platform. We can’t wait to continue working with you in the new year. https://t.co/yvxdK6aOo2",
"possibly_sensitive": false,
"referenced_tweets": [
{
"type": "replied_to",
"id": "1212092627178287104"
}
],
"entities": {
"urls": [
{
"start": 222,
"end": 245,
"url": "https://t.co/yvxdK6aOo2",
"expanded_url": "https://twitter.com/LovesNandos/status/1211797914437259264/photo/1",
"display_url": "pic.twitter.com/yvxdK6aOo2"
}
],
"annotations": [
{
"start": 144,
"end": 150,
"probability": 0.626,
"type": "Product",
"normalized_text": "Twitter"
}
]
},
"author_id": "2244994945",
"public_metrics": {
"retweet_count": 8,
"reply_count": 2,
"like_count": 40,
"quote_count": 1
},
"lang": "en",
"created_at": "2019-12-31T19:26:16.000Z",
"source": "Twitter Web App",
"in_reply_to_user_id": "2244994945",
"attachments": {
"media_keys": [
"16_1211797899316740096"
]
},
"context_annotations": [
{
"domain": {
"id": "119",
"name": "Holiday",
"description": "Holidays like Christmas or Halloween"
},
"entity": {
"id": "1186637514896920576",
"name": " New Years Eve"
}
},
{
"domain": {
"id": "119",
"name": "Holiday",
"description": "Holidays like Christmas or Halloween"
},
"entity": {
"id": "1206982436287963136",
"name": "Happy New Year: It’s finally 2020 everywhere!",
"description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
}
},
{
"domain": {
"id": "46",
"name": "Brand Category",
"description": "Categories within Brand Verticals that narrow down the scope of Brands"
},
"entity": {
"id": "781974596752842752",
"name": "Services"
}
},
{
"domain": {
"id": "47",
"name": "Brand",
"description": "Brands and Companies"
},
"entity": {
"id": "10045225402",
"name": "Twitter"
}
},
{
"domain": {
"id": "119",
"name": "Holiday",
"description": "Holidays like Christmas or Halloween"
},
"entity": {
"id": "1206982436287963136",
"name": "Happy New Year: It’s finally 2020 everywhere!",
"description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
}
}
]
}
],
"includes": {
"tweets": [
{
"possibly_sensitive": false,
"referenced_tweets": [
{
"type": "replied_to",
"id": "1212092626247110657"
}
],
"text": "These launches would not be possible without the feedback you provided along the way, so THANK YOU to everyone who has contributed your time and ideas. Have more feedback? Let us know ⬇️ https://t.co/Vxp4UKnuJ9",
"entities": {
"urls": [
{
"start": 187,
"end": 210,
"url": "https://t.co/Vxp4UKnuJ9",
"expanded_url": "https://twitterdevfeedback.uservoice.com/forums/921790-twitter-developer-labs",
"display_url": "twitterdevfeedback.uservoice.com/forums/921790-…",
"images": [
{
"url": "https://pbs.twimg.com/news_img/1261301555787108354/9yR4UVsa?format=png&name=orig",
"width": 100,
"height": 100
},
{
"url": "https://pbs.twimg.com/news_img/1261301555787108354/9yR4UVsa?format=png&name=150x150",
"width": 100,
"height": 100
}
],
"status": 200,
"title": "Twitter Developer Feedback",
"description": "Share your feedback for the Twitter developer platform",
"unwound_url": "https://twitterdevfeedback.uservoice.com/forums/921790-twitter-developer-labs"
}
]
},
"author_id": "2244994945",
"public_metrics": {
"retweet_count": 3,
"reply_count": 1,
"like_count": 17,
"quote_count": 0
},
"lang": "en",
"created_at": "2019-12-31T19:26:16.000Z",
"source": "Twitter Web App",
"in_reply_to_user_id": "2244994945",
"id": "1212092627178287104"
}
]
}
}