> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-oauth-2-ios.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/x-api/posts/lookup/introduction) 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](/x-api/fundamentals/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.

```json theme={null}
{
    "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**

<CodeBlock language="bash">
  {`curl 'https://api.x.com/2/tweets/1199786642791452673?expansions=attachments.poll_ids' --header 'Authorization: Bearer $ACCESS_TOKEN'`}
</CodeBlock>

**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**

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

**Sample Response**

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