Expansions

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

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

Available Expansion for User Payloads

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

Available Expansions for Direct Message Event Payloads

Expansion	Description
attachments.media_keys	Returns a Media object that was attached to a Direct Message
referenced_tweets.id	Returns a Post object that was referenced in a Direct Message
sender_id	Returns a User object representing the author of a Direct Message and who invited a participant to join a conversation
participant_ids	Returns a User object representing a participant that joined or left a conversation

Available Expansions for Spaces Payloads

Expansion	Description
invited_user_ids	Returns User objects representing what accounts were invited
speaker_ids	Returns User objects representing what accounts spoke during a Space
creator_id	Returns a User object representing what account created the Space
host_ids	Returns User objects representing what accounts were set up as hosts
topics_ids	Returns topic descriptions that were set up by the creator

Available Expansion for Lists Payloads

Expansion	Description
owner_id	Returns 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"
          }
      ]
  }
}`}