Expansions

Expansions enable requests to expand the complementary objects referenced in API responses. Expanding an object returns all of its fields and embeds it in a single response. Complementary objects are referenced by ID. Many ID fields within the main data payload are eligible for expansion. A request can specify which IDs should be expanded by specifying a comma-separated list of nouns and fields within the expansions request parameter.

Available expansions for /tweets

  • author_id
  • referenced_tweets.id
  • in_reply_to_user_id 
  • attachments.media_keys
  • attachments.poll_ids
  • geo.place_id

 

Available expansions for /users

  • most_recent_tweet_id
  • pinned_tweet_id


Example response:
 

{
  "data": [
    {
      "id": "1117897901500297217",
      "created_at": "2019-04-15T21:10:03.000Z",
      "text": "What is your favorite weekday of the week?",
      "author_id": "1021521993789624321",
      "in_reply_to_user_id": "1021521993789624321",
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1115482402795610112"
        }
      ],
      "attachments": {
        "poll_ids": [
          "1117897901294772224"
        ]
      },
      "format": "compact"
    }
  ],
  "includes": {
    "tweets": [
      {
        "id": "1115482402795610112",
        "created_at": "2019-04-09T05:11:44.000Z",
        "text": "Good night again",
        "author_id": "1021521993789624321",
        "format": "compact"
      }
    ],
    "users": [
      {
        "id": "1021521993789624321",
        "created_at": "2018-07-23T22:26:37.000Z",
        "name": "Tony Vu",
        "username": "sactocommuter",
        "protected": false,
        "verified": false,
        "profile_image_url": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png",
        "format": "compact"
      }
    ],
    "polls": [
      {
        "id": "1117897901294772224",
        "options": [
          {
            "position": 1,
            "label": "Monday",
            "votes": 0
          },
          {
            "position": 2,
            "label": "Tuesday",
            "votes": 0
          },
          {
            "position": 3,
            "label": "Thursday",
            "votes": 0
          },
          {
            "position": 4,
            "label": "Friday",
            "votes": 0
          }
        ],
        "voting_status": "closed",
        "end_datetime": "2019-04-16T21:10:03.000Z",
        "duration_minutes": 1440
      }
    ]
  }
}


Expansions with /tweets
 

No expansions tweet.author_id tweet.referenced_tweets.id
{
  "data": [
    {
      "id": "1108050885639168000",
      "created_at": "2019-03-19T17:01:32.000Z",
      "text": "Today we are previewing changes to the rate limits of two commonly used Twitter standard API endpoints – user and mentions timeline. Read more about the new limit that we’ll implement on June 19, 2019 here:\n\nhttps://t.co/RfrrSo4H27",
      "author_id": "6253282",
      "format": "compact"
    }
  ]
}
"includes": {
  "users": [
    {
      "id": "2244994945",
      "created_at": "2013-12-14T04:35:55.000Z",
      "name": "Twitter Dev",
      "username": "TwitterDev",
      "protected": false,
      "verified": true,
      "profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
      "format": "compact"
    }
  ]
}


"includes": {
    "tweets": [
      {
        "id": "1115482402795610112",
        "created_at": "2019-04-09T05:11:44.000Z",
        "text": "Good night again",
        "author_id": "1021521993789624321",
        "format": "compact"
      }
    ]
  }



tweet.in_reply_to_user_id tweet.attachments.media_keys tweet.attachments.poll_ids
"includes": {
    "users": [
      {
        "id": "6253282",
        "created_at": "2007-05-23T06:01:13.000Z",
        "name": "Twitter API",
        "username": "TwitterAPI",
        "protected": false,
        "verified": true,
        "profile_image_url": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg",
        "format": "compact"
      }
    ]
  }
"includes": {
    "media": [
      {
        "media_key": "3_1136066841225207808",
        "height": 326,
        "width": 260,
        "url": "https://pbs.twimg.com/media/D8QexeBUIAADxhy.png",
        "type": "photo"
      }
    ]
  }


"includes": {
  "polls": [
    {
      "id": "1117897901294772224",
      "options": [
        {
          "position": 1,
          "label": "Monday",
          "votes": 0
        },
        {
          "position": 2,
          "label": "Tuesday",
          "votes": 0
        },
        {
          "position": 3,
          "label": "Thursday",
          "votes": 0
        },
        {
          "position": 4,
          "label": "Friday",
          "votes": 0
        }
      ],
      "voting_status": "closed",
      "end_datetime": "2019-04-16T21:10:03.000Z",
      "duration_minutes": 1440
    }
  ]
}
tweet.geo.place_id    
"includes": {
  "places": [
    {
      "id": "5a110d312052166f",
      "name": "San Francisco",
      "full_name": "San Francisco, CA",
      "place_type": "city",
      "country_code": "US",
      "country": "United States",
      "format": "default"
    }
  ]
}
   

 


Expansions with /users
 

user.most_recent_tweet_id user.pinned_tweet_id
"includes": {
    "tweets": [
      {
        "id": "1158441822286303232",
        "created_at": "2019-08-05T18:17:07.000Z",
        "text": "Are you a developer in the Los Angeles area? Do you like robots and outer space? If so, sign up now to reserve your seat for the \"NASA robots and Twitter bots\" event at the Jet Propulsion Labs on Thursday, August 29th.\n\nhttps://t.co/EXXxZ6exW6",
        "author_id": "2244994945",
        "entities": {
          "urls": [
            {
              "start": 220,
              "end": 243,
              "url": "https://t.co/EXXxZ6exW6",
              "expanded_url": "https://nasarobotsandtwitterbots.splashthat.com/",
              "display_url": "…sarobotsandtwitterbots.splashthat.com"
            }
          ]
        },
        "format": "default"
      }
    ]
  }
"includes": {
   "tweets": [
     {
       "id": "1138505981460193280",
       "created_at": "2019-06-11T17:59:13.000Z",
       "text": "🎺 da-dada-DAH! We’re introducing the first Twitter Developer Labs endpoints: \n\n✨GET/users and GET/tweets ✨\n\nLabs is now open to all developers to start experimenting today 👉 https://t.co/eNx4Wc3Qwj https://t.co/ucmZrJAYjk",
       "author_id": "2244994945",
       "attachments": {
         "media_keys": [
           "7_1138489597158199298"
         ]
       },
       "entities": {
         "urls": [
           {
             "start": 174,
             "end": 197,
             "url": "https://t.co/eNx4Wc3Qwj",
             "expanded_url": "https://twittercommunity.com/t/twitter-developer-labs-is-open-to-all-developers/126717",
             "display_url": "twittercommunity.com/t/twitter-deve…"
           },
           {
             "start": 198,
             "end": 221,
             "url": "https://t.co/ucmZrJAYjk"
           }
         ]
       },
       "format": "default"
     }
   ]
 }


Additional resources