Migration guide
Overview
The latest version of the X API v2 is a big deal. As such, we’ve broken this migration section into a few partitions:
Learn more about how to use fields and expansions.
Learn more about how to use fields and expansions.
| What’s new with X API v2 | Learn about the new endpoints and functionality that we’ve released to X API v2. |
|---|---|
| Ready to migrate? | Get started with your migration with a set of guides and instructions. |
| Data format migration guide | Learn how to rework your data parsers that previously worked with the standard v1.1, and enterprise data formats. |
| X API endpoint map | See how standard v1.1, and enterprise endpoints map to the new X API v2 endpoints. |
What is the X API v2?
The X API v2 is now the primary X API, and is where product investment and innovation are focused. We’ve partnered with developers to build the next generation of the X 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 X API v2 is now the primary X 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 X API v2.Why migrate?
The X API v2 is built with a modern and more sustainable foundation and includes both improved replacement endpoints for the standard v1.1, and enterprise products, but also net-new functionality. We strongly encourage customers of legacy APIs (v1.1, and enterprise) to begin to migrate to v2 as we do intend to deprecate them eventually. Use the X API to listen to and analyze the public conversation, engage with people on X, and innovate. In this section, we will discuss the endpoints and functionality.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 X 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 X 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.
- 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
X API v2 also includes new features that will help you find more value with the X 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:- A consistent design across endpoints
- The ability to specify which fields and objects return in the response payload
- New and more detailed data objects
- Receive and filter data with new contextual information powered by Tweet annotations
- Access to new metrics
- Easily identify and filter for conversations that belong to a reply thread
- Advanced functionality and increased access to data for academic researchers
- Recovery and redundancy functionality for streaming endpoints
- Easily return counts of Tweets that match a query
- Support for Edit Tweets
- High confidence spam filtering
- Shortened URLs are fully unwound for more effective filtering and analysis
- Simplified JSON response objects by removing deprecated fields and modernizing labels
- Return of 100% of matching public and available Tweets in search queries
- Streaming “rules” so you can make changes without dropping connections
- More expressive query language for search Tweets, Tweet counts, and filtered stream
- OpenAPI spec to build new libraries & more transparently track changes
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 X 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 theid 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 X API v2 endpoints:
| Object / Resource | Available Expansions |
|---|---|
| Tweets | author_id, edit_history_tweet_ids, 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 |
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.| Object | Available Metrics | Public Metrics | Private Metrics | Organic Metrics | Promoted Metrics |
|---|---|---|---|---|---|
| tweets | retweet_count | ✔️ | ✔️ | ✔️ | |
| quote_count | ✔️ | ||||
| like_count | ✔️ | ✔️ | ✔️ | ||
| reply_count | ✔️ | ✔️ | ✔️ | ||
| impression_count | ✔️ | ✔️ | ✔️ | ||
| url_profile_clicks | ✔️ | ✔️ | ✔️ | ||
| url_link_clicks | ✔️ | ✔️ | ✔️ | ||
| user | follower_count | ✔️ | |||
| user | following_count | ✔️ | |||
| media | view_count | ✔️ | |||
| media | playback_0_count | ✔️ | |||
| space | participant_count | ✔️ |
Edit Tweets
The X API v2 endpoints provide edited Tweet metadata. The Edit Tweet feature was first introduced for testing among X employees on September 1, 2022. Starting on that date, eligible Tweets are editable for 30 minutes and up to 5 times. Learn more about Edit Tweets. Using the X 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.
Track Threaded Conversations
A new Tweet field helps identify which conversation thread a Tweet belongs to. A conversation ID is the Tweet ID of the Tweet that started the conversation. Learn more about conversation tracking.Ready to migrate
In order to use v2 endpoints, you will need the following things:- A developer account
- A developer App created within a Project
- Keys and tokens from that Project’s developer App
Authentication
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 different endpoints. Each serves a different purpose when making requests to the endpoints: OAuth 1.0a User Context is required when making a request on behalf of a Twitter user OAuth 2.0 Bearer token is required to make requests on behalf of your developer AppTools 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:- 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.
- 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 endpoint’s capabilities compared to older versions:- Tweets
- Users
- Lists
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 is delivered in has changed significantly. We have added new fields, modified the sequence of fields, and in some cases removed elements altogether. 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 describe 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:- Native format to x API v2 (standard v1.1)
- Native Enriched to X API v2 (enterprise)
- Activity Streams to X API v2 (enterprise)