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

  • author_id
  • referenced_tweets.id
  • in_reply_to_user_id 
  • attachments.media_keys
  • attachments.poll_ids
  • geo.place_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"
    }
  ]
}



































   


Additional resources