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 Posts lookup payload can be expanded into complete objects. If you would like to request fields related to the user that posted that Post, or the media, poll, or place that was included in that Post, you will need to pass the related expansion query parameter in your request to receive that data in your response. Currently, v2 endpoints that return Posts, Users, Lists, Spaces, and Direct Message event objects all support expansions (see examples below).

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.

The Post payload below contains reference IDs for complementary objects we can expand on, including the author_id of who posted the Post, the id of a referenced Post, and a media_key for a media attachment.

{
    "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"
    }
}

​
Available Expansions for Post Payloads

ExpansionDescription
author_idReturns a user object representing the Post’s author
referenced_tweets.idReturns a Post object that this Post is referencing (either as a Retweet, Quoted Tweet, or reply)
edit_history_tweet_idsReturns Post objects that are part of a Post’s edit history
in_reply_to_user_idReturns a user object representing the Post author this requested Post is a reply of
attachments.media_keysReturns a media object representing the images, videos, GIFs included in the Post
attachments.poll_idsReturns a poll object containing metadata for the poll included in the Post
geo.place_idReturns a place object containing metadata for the location tagged in the Post
entities.mentions.usernameReturns a user object for the user mentioned in the Post
referenced_tweets.id.author_idReturns a user object for the author of the referenced Post

​
Available Expansion for User Payloads

ExpansionDescription
pinned_tweet_idReturns a Post object representing the Post pinned to the top of the user’s profile

​
Available Expansions for Direct Message Event Payloads

ExpansionDescription
attachments.media_keysReturns a Media object that was attached to a Direct Message
referenced_tweets.idReturns a Post object that was referenced in a Direct Message
sender_idReturns a User object representing the author of a Direct Message and who invited a participant to join a conversation
participant_idsReturns a User object representing a participant that joined or left a conversation

​
Available Expansions for Spaces Payloads

ExpansionDescription
invited_user_idsReturns User objects representing what accounts were invited
speaker_idsReturns User objects representing what accounts spoke during a Space
creator_idReturns a User object representing what account created the Space
host_idsReturns User objects representing what accounts were set up as hosts
topics_idsReturns topic descriptions that were set up by the creator

​
Available Expansion for Lists Payloads

ExpansionDescription
owner_idReturns a User object representing what account created and maintains the List

​
Expanding the Media Object

In the following request, we are requesting the geo.place_id expansion to include alongside the default Post fields:

Sample Request

{`curl 'https://api.x.com/2/tweets/:ID?expansions=geo.place_id' --header 'Authorization: Bearer $ACCESS_TOKEN'`}

Sample Response

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

​
Expanding the Poll Object

In the following request, we are requesting the attachments.poll_ids expansion to include alongside the default Post fields:

Sample Request

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 geo.place_id expansion to include alongside the default Post fields:

Sample Request

Sample Response

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