What is the new Twitter API v2?

Over the past few years, 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.

 

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. 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 three 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. 

Essential

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

Elevated

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

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:

Object

Description

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.
Lists

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
entities.mentions.username
in_reply_to_user_id
referenced_tweets.id
referenced_tweets.id.author_id
attachments.poll_ids
attachments.media_keys
geo.place_id
Users pinned_tweet_id
Spaces invited_user_ids
speaker_ids
creator_id
host_ids
topic_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   ✔️    
playback_0_count
playback_25_count
playback_50_count
playback_75_count
playback_100_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"
        }
      ]

    


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.