Welcome to the new Twitter API! 

We believe developers play a critical role in serving the public conversation. The creativity of developers with our API makes Twitter better for people and businesses, and makes the world a better place. As we embark on the next phase of our API, our objective is to make our developer platform better for everyone. 

Our API gives you the ability to learn from and analyze the conversation on Twitter. We want to give you the tools you need to further uncover, build on, and share the value of this conversation with the world. 

Over the past year, we’ve partnered with developers to build the next generation of the Twitter API to better serve our diverse community of developers. Based on developer feedback we’ve re-designed the API to better serve a broader collection of needs, introduced new capabilities and provided room for developers to grow more seamlessly. This is just the beginning.

What is the new Twitter API?

In May of 2019, we announced our intent to build the next generation of the Twitter API. Since then, we have been collecting feedback and learning from the Twitter developer community. After more than a year of collaboration, we are announcing the first collection of Twitter API v2 endpoints. Longer term, as we release new versions of core endpoints and features, you should expect they will replace the standard v1.1premium v1.1, and enterprise endpoints as you know them today. The endpoints we have released so far are:

Resource Endpoint group How it can be used
Tweets Tweet lookup Look up Tweets by ID.
Search Tweets

Query the most recent seven days or the full-archive of Tweets, and receive a full-fidelity response.

The full-archive search endpoint is currently only available via the Academic Research product track.

Tweet counts

Retrieve a count of Tweets from either the last seven days or from the full-archive that matches a query.

The full-archive Tweet counts endpoint is currently only available via the Academic Research product track.

Timelines Retrieve a timeline of either the Tweets composed by a specified Twitter account, or the mentions of a specified Twitter account.
Filtered stream Filter the complete stream of real-time public Tweets.
Sampled stream Stream a sample of new Tweets as they are published, across ~1% of all public Tweets in real-time.
Retweets Retrieve a list of accounts that have Retweeted a Tweet, or Retweet or undo a Retweet of a Tweet.
Likes Retrieve a list of users who liked a Tweet, retrieve a list of Tweets that a user has liked, or like and unlike a Tweet.
Hide replies Hide or unhide a reply to a Tweet.
Users User lookup Look up users by name or ID.
Follows Retrieve an account's followers, retrieve a list of who an account is following, or follow and unfollow a user.
Blocks Retrieve a list of users that an account has blocked, or block and unblock a user.
Mutes Retrieve a list of users that an account has muted, or mute and unmute a user

If you currently use the standard v1.1 endpoints, the chart below reflects the functional replacement of a subset of the  v1.1 endpoints with their v2 successors along with the v2 request rate limits for each.

Standard v1.1 endpoints v2 endpoint v2 limits
statuses/show & statuses/lookup Tweet lookup 900 requests/15 min per user
300 requests/15 min per App
statuses/user_timeline & statuses/mentions_timeline Timelines
- User Tweet timeline
- User mention timeline
User Tweet timeline
900 requests/15 min per user
1500 requests/15 min per App

User mentions timeline
180 requests/15 min per user
450 requests/15 min per App
search/tweets Search Tweets
- Recent search
- Full-archive search
Recent search
450 requests/15 min per user
180 requests/15 min per App

Full-archive search
300 requests/15 min per App
1 request/1 sec per App
  Tweet counts
- Recent Tweet counts
- Full-archive Tweet counts

Recent Tweet counts
300 requests/15 min per App

Full-archive Tweet counts
300 requests/15 min per App

statuses/filter Filtered stream
- Connect to stream
- Add/delete rules
- Retrieve rules
Connect to stream
50 requests/15 min per App

Add/delete rules
450 requests/15 min per App

Retrieve rules
450 requests/15 min per App
statuses/sample Sampled stream 50 requests/15 min per App
statuses/retweets/:id & statuses/retweeters/:ids Retweets lookup 75 requests/15 min per user
75 requests/15 min per App
statuses/retweet/:id & statuses/unretweet/:id

Manage Retweets
- Retweet a Tweet
- Undo a Retweet


- 50 requests/15 min
- 50 requests/15 min

300 requests/3 hours

favorites/list (Tweets liked by a user)

Users who have liked a Tweet is a new endpoint in v2

Likes lookup
- Tweets liked by a user
- Users who have liked a Tweet

Tweets liked by a user
75 requests/15 min per user
75 requests/15 min per App

Users who have liked a Tweet
75 requests/15 min per user
75 requests/15 min per App

favorites/create, favorites/destroy

Manage Likes
- Like a Tweet
- Unlike a Tweet

Shared rate limit

50 requests/15 min per user
50 requests/15 min per user

1000 requests/24 hour per user

  Hide replies 50 requests/15 min
users/show & users/lookup User lookup 900 requests/15 min per user
300 requests/15 min per App
followers/ids, followers/list, friends/ids, & friends/list Follows lookup 15 requests/15 min per user
15 requests/15 min per App
friendships/create, friendships/destroy Manage follows
- Follow a user
- Unfollow a user

50 requests/15 min per user
50 requests/15 min per user
blocks/ids, blocks/list Blocks lookup 15 requests/15 min per user
blocks/create, blocks/destroy Manage blocks
- Block a user
- Unblock a user

50 requests/15 min per user
50 requests/15 min per user
mutes/users/ids, mutes/users/list Mutes lookup 15 requests/15 min per user
mutes/users/create, mutes/users/destroy Manage mutes
- Mute a user
- Unmute a user

50 requests/15 min per user
50 requests/15 min per user

Learn more about rate limits


Learn about what's new and different

We’ve included some new features and functionality that will help you find more value with the Twitter API. A lot of what is new has been driven by your feedback. Some of the improvements to the API include:

Before you dive in, let’s cover some of the fundamental changes we’ve made to the way you will access and consume data from the endpoints. 

Discover new and updated data objects

The following five data objects are available with the v2 endpoints:



Tweet The Tweet object has a long list of root-level fields, such as id, text, and created_at. Tweet objects are also the parent object to several child objects including user, media, poll, and place.
User The user object contains Twitter user account metadata describing the referenced user.
Media If a Tweet contains media (such as images), then the media object can be requested using the media.fields parameter and includes fields such as the media_key, type, url, preview_image_url, and more. 
Poll A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object.
Place The place object consists of fields such as place_id, geo object, country_code, and more. This information can be used to identify Tweets and study Tweets by location.

Flexiblity to choose which data objects and fields you receive

When making a request to a GET endpoint, you will receive the primary data object that relates to that endpoint, which will include a set of default fields. For example, the Tweet object delivers the id and text fields as its default. 

If you would like to retrieve additional fields with your request, you will have to use the fields parameter. You can also request related objects using the expansions parameter, such as a user's pinned Tweet or a media object, and then an additional fields parameter to pull any fields from this related object. Here is a full list of expansions that you can request with the different Twitter API v2 endpoints:

  • author_id
  • in_reply_to_user_id
  • attachments.media_keys
  • attachments.poll_ids
  • geo.place_id
  • pinned_tweet_id
  • entities.mentions.username
  • referenced_tweets.id.author_id

Learn more about how to use fields and expansions, and check out our full list of data objects and fields in the Twitter API v2 data dictionary.

    "data": {
        "attachments": {
            "media_keys": [
        "author_id": "783214",
        "created_at": "2020-05-12T19:44:51.000Z",
        "id": "1260294888811347969",
        "public_metrics": {
            "retweet_count": 5240,
            "reply_count": 1844,
            "like_count": 17168,
            "quote_count": 3275
        "source": "Sprinklr",
        "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y"


New metrics available within Tweets, users, and media objects

More metrics are now accessible within Tweet, user, and media objects. These metrics are both public and private, and some metrics can be broken down into an organic or promoted context for Tweet ads. 

Learn more about the available metrics.

    All Tweets Ads
Object Available metrics Public metrics Private metrics
(requires OAuth 1.0a User Context auth)
Organic metrics Promoted metrics
tweets retweet_count ✔️   ✔️ ✔️
quote_count ✔️      
like_count ✔️   ✔️ ✔️
reply_count ✔️   ✔️ ✔️
impression_count   ✔️ ✔️ ✔️
url_profile_clicks   ✔️ ✔️ ✔️
url_link_clicks   ✔️ ✔️ ✔️
user follower_count ✔️      
following_count ✔️      
tweet_count ✔️      
listed_count ✔️      
media view_count   ✔️    
       "public_metrics": {
            "retweet_count": 5239,
            "reply_count": 1844,
            "like_count": 17168,
            "quote_count": 3275

  "non_public_metrics": {
            "impression_count": 956,
            "user_profile_clicks": 34,
            "url_link_clicks": 57

   "organic_metrics": {
            "impression_count": 956,
            "like_count": 1244,
            "reply_count": 300,
            "user_profile_clicks": 150
            "url_link_clicks": 57

   "promoted_metrics": {
            "impression_count": 25086,
            "like_count": 9045,
            "reply_count": 637,
            "user_profile_clicks": 265,
            "url_link_clicks": 48

Tweet annotations

Annotations can be used to discover Tweets on topics of interest or to segment Tweets by entity categories. Tweets are analyzed and annotated based on the content of the Tweet text by both semantic labeling and internal machine learning algorithms. These annotations are now available via API in the response payload. We call these new elements “annotations” and they are delivered as two fields, context_annotations and entity, and can be used to filter search and streaming results using operators by the same name. 

Learn more about Tweet annotations.

      "context_annotations": [
        "domain": {
          "id": "45",
          "name": "Brand Vertical",
          "description": "Top level entities that describe a Brands industry"
        "domain": {
          "id": "46",
          "name": "Brand Category",
          "description": "Categories within Brand Verticals that narrow down the scope of Brands"
        "entity": {
          "id": "781974596752842752",
          "name": "Services"
        "domain": {
          "id": "47",
          "name": "Brand",
          "description": "Brands and Companies"
        "entity": {
          "id": "10026364281",
          "name": "Apple"
        "domain": {
          "id": "48",
          "name": "Product",
          "description": "Products created by Brands.  Examples: Ford Explorer, Apple iPhone."
        "entity": {
          "id": "10044903039",
          "name": "Apple - iOS"
    "created_at": "2020-05-12T19:44:51.000Z",
    "entities": {
      "annotations": [
          "start": 49,
          "end": 51,
          "probability": 0.8997,
          "type": "Product",
          "normalized_text": "iOS"


Track threaded conversations

A new filter operator, conversation_id, matches Tweets that share a common conversation ID, and is available for both recent search and filtered stream. A conversation ID is the Tweet ID of the Tweet that started the conversation. When a Tweet is part of a conversation thread, the conversation ID for that Tweet will match the parent most Tweet ID. 

Learn more about conversation ID.

Get Started

In order to use v2 endpoints you will need the following things to get started. 

You can add an existing App to your new Project. While you are setting up your Project you should see an option to add any of your standalone Apps.

For additional information on how to proceed once you’ve obtained an approved Twitter developer account account check out our Getting Started guide.

If you are academic researcher, then you can apply for the Academic Research product track. If you are eligible, this will give you access to an academic project that will give you access to the full-archive search endpoint, a higher monthly Tweet cap and enhanced filtering capabilities on the filtered stream and recent search endpoints. Learn more about the Academic Research product track on our academic research hub.


With the new Twitter API, you’ll use two different authentication patterns,  OAuth 1.0a User Context and OAuth 2.0 Bearer token, to access each endpoint. Each serves a different purpose when making requests to the endpoints. OAuth 2.0 Bearer token is required to make requests on behalf of your developer App, whereas OAuth 1.0a User Context authentication is required when making a request on behalf of others Twitter users.

Tools and Code 

To help you get started and familiarize yourself with the new endpoints and capabilities we have a few options to jump start your work:

First, we have a Twitter Postman collection that allows you to use the Postman client to make requests of and connect to the individual endpoints. This is a low friction way to test authentication and experiment with the endpoints. It’s important to note the Postman client is best for RESTful endpoints, but you can copy requests to streaming endpoints from the tool and paste them into your command line tool.

If you want to dig deeper, we’ve also provided a list of both Twitter supported and third party libraries in Ruby, Python, Node, Java, and many more. For additional context, take a look at our tools and libraries page.

Migrating to updated endpoints

As you start to explore the new Twitter v2 endpoints, we’ve built a series of detailed migration guides to help you compare and contrast each updated endpoints' capabilities compared to older versions:


Migrating to the new data format

As you move from v1.1 or enterprise to v2, it is important to understand that the format the data are delivered in has changed significantly. We have added new fields, modified the sequence of fields and in some cases removed elements as well. 

To learn more about these changes, we are developing a series of guides that will help you map out the pre-v2 data format fields to the newer fields, and describes how to request these new fields. 

You can learn more by visiting our data formats migration section of this migration hub, or by visiting our specific data format guides:

What’s next?

Those of you who have used the platform for some time will notice that many of the new endpoints are aligned with existing standard v1.1, premium v1.1, and enterprise endpoints. Indeed, we intend for these to replace all three versions in the future. For more details on what we’re planning, including our planned sequence of releases and migrations, take a look at our “Guide to the future of the Twitter API”


Stay up to date

The Twitter API will rapidly evolve from here. To see what we plan to do next, take a look at our roadmap. As things progress you may also track what we’ve been up to at a more granular level use our changelog.


What should we build next?

As we build out additional capabilities of the Twitter API v2 we want to continue to hear from you. We welcome and encourage feedback from you. 

Take a look at the ideas that have already been submitted, show your support for those that correlate with your needs and provide feedback as well!

Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.