Expansions

Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.

Overview

Expansions enable requests to expand the complementary objects referenced in API responses. Expanding an object returns its default 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
  • entities.mentions.username
  • referenced_tweets.id.author_id

 

Available expansions for /users

  • pinned_tweet_id


Example response:
 

      {
    "data": {
        "attachments": {
            "poll_ids": [
                "1117897901294772224"
            ]
        },
        "author_id": "1021521993789624321",
        "id": "1117897901500297217",
        "in_reply_to_user_id": "1021521993789624321",
        "text": "What is your favorite weekday of the week?"
    },
    "includes": {
        "polls": [
            {
                "id": "1117897901294772224"
            }
        ],
        "users": [
            {
                "id": "1021521993789624321",
                "name": "Tony Vu",
                "username": "sactocommuter"
            }
        ],
        "places": [
            {
                "id": "5a110d312052166f"
            }
        ],
        "tweets": [
            {
                "author_id": "1021521993789624321",
                "id": "1115482402795610112",
                "text": "Good night again"
            }
        ]
    }
}


Expansions with /tweets
 

No expansions tweet.author_id tweet.referenced_tweets.id 
{
  "data": [
    {
      "id": "1108050885639168000",
      "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"
    }
  ]
}

"includes": {
  "users": [
    {
      "id": "2244994945",
      "name": "Twitter Dev",
      "username": "TwitterDev"
    }
  ]
}

"includes": {
    "tweets": [
      {
        "id": "1115482402795610112",
        "text": "Good night again"
      }
    ]
  }
tweet.in_reply_to_user_id tweet.attachments.media_keys tweet.attachments.poll_ids 
"includes": {
    "users": [
      {
        "id": "6253282",
        "name": "Twitter API",
        "username": "TwitterAPI"
      }
    ]
  }

"includes": {
    "media": [
      {
        "media_key": "3_1136066841225207808"
      }
    ]
  }

"includes": {
  "polls": [
    {
      "id": "1117897901294772224"
    }
  ]
}
tweet.geo.place_id     
"includes": {
  "places": [
    {
      "id": "5a110d312052166f"
    }
  ]
}
   

 


Expansions with /users
 

user.pinned_tweet_id   
"includes": {
    "tweets": [
      {
        "id": "1214281000932593667",
        "text": "Hello… is it me you’re searching for? 🔎\n\nSearch the conversation as it unfolds with this new addition to Labs. We're making it easier than ever to find the Tweets you care about. https://t.co/HmuuUC6PKZ https://t.co/QgEXeL9XzX"
      }
    ]
  }


Additional resources