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 is the primary object returned on the following endpoints:

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.

"id": "1050118621198921728"

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.

"text": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin tone modifiers 👍🏻👍🏽👍🏿. This is now reflected in Twitter-Text, our Open Source library. \n\nUsing Twitter-Text? See the forum post for detail: https://t.co/Nx1XZmRCXA"


Keyword extraction and sentiment analysis/classification.

attachments

object

Specifies the type of attachments (if any) present in this Tweet.

"attachments": {
    "poll_ids": [
        "1199786642468413448"
    ]
}

"attachments": {
    "media_keys": [
        "3_1136048009270239232"
    ]
}

Understanding the objects returned for requested expansions 

author_id

string

The unique identifier of the User who posted this Tweet.

"author_id": "2244994945"

Hydrating User object, sharing dataset for peer review

context_annotations

array

Contains context annotations for the Tweet.

"context_annotations": [
      {
           "domain": {
               "id": "45",
               "name": "Brand Vertical",
               "description": "Top level entities that describe a Brands industry"
           }
       },
       {
           "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"
           }
       }
   ]

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).

"conversation_id": "1050118621198921728"

Use this to reconstruct the conversation from a Tweet.

created_at

date (ISO 8601)

Creation time of the Tweet.

"created_at": "2019-06-04T23:12:08.000Z"

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": {
    "annotations": [
        {
           "start": 144,
           "end": 150,
           "probability": 0.626,
           "type": "Product",
           "normalized_text": "Twitter"
        }
    ],
   "cashtags": [
        {
            "start": 18,
            "end": 23,
            "tag": "twtr"
        }
    ],
    "hashtags": [
        {
            "start": 0,
            "end": 17,
            "tag": "blacklivesmatter"
        }
    ],
    "mentions": [
        {
            "start": 24,
            "end": 35,
            "tag": "TwitterDev"
        }
    ],
    "urls": [
        {
           "start": 44,
           "end": 67,
           "url": "https://t.co/crkYRdjUB0",
           "expanded_url": "https://twitter.com",
           "display_url": "twitter.com",
           "status": "200",
           "title": "bird",
           "description": "From breaking news and entertainment to sports and politics, get the full story with all the live commentary.",
            "unwound_url": "https://twitter.com"
        }
    ]
}

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.

geo

object

Contains details about the location tagged by the user in this Tweet, if they specified one.

"geo": {
       "coordinates": {
           "type": "Point",
           "coordinates": [
               -73.99960455,
               40.74168819
           ]
       },
       "place_id": "01a9a39529b27f36"
   }

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.

"in_reply_to_user_id": "2244994945"

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.

"lang": "en"

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.

"non_public_metrics": {
      "impression_count": 99
      "url_link_clicks": 37
      "user_profile_clicks": 22
 }


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.

"organic_metrics": {
     "impression_count": 3880,
     "like_count": 8,
     "reply_count": 0,
     "retweet_count": 4
     "url_link_clicks": 3
     "user_profile_clicks": 2
}

Use this to measure organic engagement for the Tweet.

possiby_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. 

"possibly_sensitive": false

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.

"promoted_metrics": {
      "impression_count": 1082,
      "like_count": 187,
      "reply_count": 6,
      "retweet_count": 25
      "url_link_clicks": 30
      "user_profile_clicks": 2
 }


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.

"public_metrics" : {
         "retweet_count": 8,
         "reply_count": 2,
         "like_count": 39,
         "quote_count": 1
 }

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.

"referenced_tweets": [
       {
           "type": "replied_to",
           "id": "1242125486844604425"
       }
   ]


"referenced_tweets": [
       {
           "type": "quoted",
           "id": "1265712391578214400"
       }
   ]


This field can be used to understand conversational aspects of retweets etc.

source

string

The name of the app the user Tweeted from.

"source": "Twitter Web App"

Determine if a Twitter user posted from the web, mobile device, or other app.

withheld

object

When present, contains withholding details for withheld content.

"withheld": {
       "copyright": false,
       "country_codes": [
          "IN"
       ]
   }

 


Retrieving a Tweet object

Sample Request

In the following request, we are requesting fields for the Tweet on the Tweet 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"
            }
        ]
    }
}

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.