Expansions

Overview

With expansions, developers can expand objects referenced in the payload. Objects available for expansion are referenced by ID. For example, the referenced_tweets.id and author_id fields returned in the Tweets lookup payload can be expanded into complete objects. If you would like to request fields related to the user that posted that Tweet, or the media, poll, or place that was included in that Tweet, you will need to pass the related expansion query parameter in your request to receive that data in your response.

When including an expansion in your request, we will include that expanded object’s default fields within the same response. It helps return additional data in the same response without the need for separate requests. If you would like to request additional fields related to the expanded object, you can include the field parameter associated with that expanded object, along with a comma-separated list of fields that you would like to receive in your response. Please note fields are not always returned in the same order they were requested in the query.

{
    "data": {
        "attachments": {
            "media_keys": [
                "16_1211797899316740096"
            ]
        },
        "author_id": "2244994945",
        "id": "1212092628029698048",
        "referenced_tweets": [
            {
                "type": "replied_to",
                "id": "1212092627178287104"
            }
        ],
        "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"
    }
}

The Tweet payload above contains some reference IDs for complementary objects we can expand on. We can expand on attachments.media_keys to view the media object, author_id to view the user object, and referenced_tweets.id to view the Tweet object the originally requested Tweet was referencing. Expanded objects will be nested in the "includes" object, as can be seen in the sample response below.

 

Available expansions in a Tweet payload

Expansion Description
author_id Returns a user object representing the Tweet’s author
referenced_tweets.id Returns a Tweet object that this Tweet is referencing (either as a Retweet, Quoted Tweet, or reply)
in_reply_to_user_id Returns a user object representing the Tweet author this requested Tweet is a reply of
attachments.media_keys Returns a media object representing the images, videos, GIFs included in the Tweet
attachments.poll_ids Returns a poll object containing metadata for the poll included in the Tweet
geo.place_id Returns a place object containing metadata for the location tagged in the Tweet
entities.mentions.username Returns a user object for the user mentioned in the Tweet
referenced_tweets.id.author_id Returns a user object for the author of the referenced Tweet

 

Available expansion in a user payload

Expansion Description
pinned_tweet_id Returns a Tweet object representing the Tweet pinned to the top of the user’s profile

 

Expanding the media, Tweet, and user objects

In the following request, we are requesting the following expansions to include alongside the default Tweet fields.  Be sure to replace $BEARER_TOKEN with your own generated bearer token.

  • attachments.media_keys
  • referenced_tweets.id
  • author_id

 

Sample Request

 

  curl 'https://api.twitter.com/2/tweets/1212092628029698048?expansions=attachments.media_keys,referenced_tweets.id,author_id' --header 'Authorization: Bearer $BEARER_TOKEN'

 

Sample Response

{
    "data": {
        "attachments": {
            "media_keys": [
                "16_1211797899316740096"
            ]
        },
        "author_id": "2244994945",
        "id": "1212092628029698048",
        "referenced_tweets": [
            {
                "type": "replied_to",
                "id": "1212092627178287104"
            }
        ],
        "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"
    },
    "includes": {
        "media": [
            {
                "media_key": "16_1211797899316740096",
                "type": "animated_gif"
            }
        ],
        "users": [
            {
                "id": "2244994945",
                "name": "Twitter Dev",
                "username": "TwitterDev"
            }
        ],
        "tweets": [
            {
                "author_id": "2244994945",
                "id": "1212092627178287104",
                "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"
            }
        ]
    }
}

Expanding the poll object

In the following request, we are requesting the following expansions to include alongside the default Tweet fields:

  • attachments.poll_ids

 

Sample Request

  curl 'https://api.twitter.com/2/tweets/1199786642791452673?expansions=attachments.poll_ids' --header 'Authorization: Bearer $BEARER_TOKEN'

Sample Response

{
    "data": {
        "attachments": {
            "poll_ids": [
                "1199786642468413448"
            ]
        },
        "id": "1199786642791452673",
        "text": "C#"
    },
    "includes": {
        "polls": [
            {
                "id": "1199786642468413448",
                "options": [
                    {
                        "position": 1,
                        "label": "“C Sharp”",
                        "votes": 795
                    },
                    {
                        "position": 2,
                        "label": "“C Hashtag”",
                        "votes": 156
                    }
                ]
            }
        ]
    }
}

Expanding the place object

In the following request, we are requesting the following expansions to include alongside the default Tweet fields:

  • geo.place_id

 

Sample Request

  curl 'https://api.twitter.com/2/tweets/:ID?expansions=geo.place_id’ --header 'Authorization: Bearer $BEARER_TOKEN'

Sample Response

{
    "data": {
        "geo": {
            "place_id": "01a9a39529b27f36"
        },
        "id": "ID",
        "text": "Test"
    },
    "includes": {
        "places": [
            {
                "full_name": "Manhattan, NY",
                "id": "01a9a39529b27f36"
            }
        ]
    }
}

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.