What's new

What is the Twitter API v2?

The Twitter API v2 is now the primary Twitter API, and is where product investment and innovation are focused. 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-built the API to better serve a broader collection of needs, introduced new features and endpoints, and improved upon the developer experience.


The Twitter API v2 is now the primary Twitter API, and is where product investment and innovation are focused. Over the past few years, we partnered with developers and re-built the API to better serve a broader collection of needs, introduce new features and endpoints, and improve upon the developer experience. We are committed to continuing to build an open developer platform, and are excited to see what you build with the Twitter API v2.


Why migrate?

The Twitter API v2 is built with a modern and more sustainable foundation and includes both improved replacement endpoints for the standard v1.1, premium v1.1, and enterprise products, but also net-new functionality. We strongly encourage customers of legacy APIs (v1.1, premium, and enterprise) to begin to migrate to v2 as we do intend to deprecate them eventually. Use the Twitter API to listen to and analyze the public conversation, engage with people on Twitter, and innovate.  

In this section, we will discuss the new access levels, endpoints, and functionality.


Access levels

The Twitter API v2 introduces a new set of access levels that will help you get started quickly and scale your usage as you grow on the platform.

There are currently four different access levels available to the Twitter API, but if you need more access than what is currently available, we recommend that you sign up for our waitlist to learn more about future releases. 


With Essential access, you can now get access to Twitter API v2 quickly and for free! 

  • Retrieve 500,000 Tweets per month
  • 1 Project per account
  • 1 App environment per Project
  • No access to standard v1.1, premium v1.1, or enterprise


With Elevated access, you can get free, additional access to endpoints and data, as well as additional App environments.

  • Retrieve 2 million Tweets per month
  • 1 Project per account
  • 3 App environments per Project
  • Access to standard v1.1, premium v1.1, and enterprise

Academic Research

If you qualify for our Academic Research access level, you can get access to even more data and advanced search endpoints.

  • Retrieve 10 million Tweets per month
  • Access to full-archive search and full-archive Tweet counts
  • Access to advanced search operators


Enterprise access to the Twitter API v2 supports the highest volumes of access an dincludes enterprise-grade features.

  • Retrieve 10+ million Tweets per month
  • Access to full-archive search and full-archive Tweet counts
  • Access to advanced search operators
  • 3+ App Environments per project
  • Advanced reliability features
  • Specialized streams
  • Account management + support

Please note:

If you were approved for a developer account before November 15th, 2021, will were automatically converted to Elevated access. This means that your existing Apps can continue to be used to make requests to standard v1.1, premium v1.1, and enterprise endpoints, and that all of your user Access Tokens are still valid.

If you would like to start using v2 endpoints, you will need to attach an App to a Project and use the credentials from that App when making requests to v2 endpoints. 


V2 endpoints

You can see a full list of v2 endpoints and their pre-v2 equivalent via the following guide:

While most of the endpoints in Twitter API v2 are replacements, we have introduced several new endpoints. Here are several examples of new endpoints that we’ve released to v2:

  • Spaces endpoints to help people get more out of Twitter Spaces, and to allow developers to help shape the future of audio conversations.
  • Hide replies, which allows you to build tools that help limit the impact of abusive, distracting, or misleading replies at scale – a crucial piece to improving the health of the public conversation on Twitter, and ensuring brands and people feel comfortable starting conversations.
  • New Lists endpoints that allow you to pin and unpin Lists, or look up someone’s pinned Lists
  • New batch compliance endpoints that allow you to ensure your stored user and Tweet data is in compliance.


New functionality

Twitter API v2 also includes new features that will help you find more value with the Twitter API. A lot of what is new has been driven by your feedback, and includes certain features that were reserved for enterprise customers previously. 

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 response objects

The following six 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.
Spaces The Space object consists of fields such as state, host_id, is_ticketed, and even lang.

The List object contains basic information about the requested list including description, member_count, and owner_id.

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.


Flexibility to choose which 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 and expansions parameters. The expansions parameter enables you to retrieve related data objects such as a user's pinned Tweet or a media object, while the field operators enable you to request specific fields within returned objects beyond the defaults. 

Here is a full list of expansions that you can request with the different Twitter API v2 endpoints:

Object / Resource Available expansions
Tweets author_id
Users pinned_tweet_id
Spaces invited_user_ids

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.



New metrics available within Tweets, users, Spaces, and media objects

More metrics are now accessible within Tweet, user, Spaces, Lists, 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   ✔️    
space participant_count ✔️      
subscriber_count   ✔️    
list follower_count
member_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 (context annotations) and internal machine learning algorithms (named entity recognition). 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 Tweets, Tweet counts, and filtered stream responses.

Learn more about Tweet annotations.

Here is an example of what this would look like in your payload:

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


Edit Tweets

The Twitter API v2 endpoints provide edited Tweet metadata. The Edit Tweet feature was first introduced for testing among Twitter employees on September 1, 2022. Starting on that date, eligible Tweets are editable for 30 minutes and up to 5 times. Also, all objects for Tweets since September 29, 2022  include Tweet edit metadata, even if the Tweet was never edited. Each time a Tweet is edited, a new Tweet ID is created. A Tweet's edit history can be described by chaining these IDs together, starting with the original ID.  

Using the Twitter API v2, a developer can find out:

  • If a Tweet was edit eligible at the time of creation. Some Tweets, such as those with polls or scheduled Tweets, can not be edited.
  • Tweets are editable for 30 minutes, and can be edited up to 5 times. For editable Tweets you can see if time for editing remains and how many more edits are possible.
  • If you are viewing an edited version of a Tweet (in most cases the API will return the most recent version of a Tweet, unless a specific past version is requested by Tweet ID).
  • The entire edit history of the Tweet.
  • The engagement attributed to each version of the Tweet.

Learn more about Edit Tweets.

Track threaded conversations

We have introduced a new Tweet field to help you identify which conversation thread that Tweet belongs to. In addition to this, we launched a new filter operator that matches Tweets that share a common conversation ID, and is available for search Tweets, Tweet counts, and filtered stream. 

A conversation ID is the Tweet ID of the Tweet that started the conversation. 

Learn more about conversation tracking.