X API v2 support

Frequently asked questions about the X API v2 setup and access

What is v2?

X API v2 is the latest version of the X API that can be used by all X developers. X Developer Platform originally launched Early Access to give developers a preview of the v2 API back in June 2020, and in November 2021 we launched a production ready, stable version of v2 for all developers. 

The functionality available within X API v2 serves the majority of developers on the platform. The X API v2 is the latest version of the single platform that will eventually replace the current standard v1.1 and enterprise APIs.

For more detail about our plans for the new X API, visit our “Guide to the future”.

How can I try the X API v2 right now?

X API tools includes the X API Playground which helps you to test out several X API v2 endpoints even before signing up for an account. Get started with a simple username lookup here, or search for recent Posts with a simple keyword query here. 

If I'm brand new to the X API, which version should I use?

It's advantageous for all new X developers to start with the most recent and supported version of the API, which is v2. Any new features will be released on X API v2.

Is the X API v2 stable, ready for production use?

Yes, after November 15th, 2021 the X API v2 is the recommended API for development.

How can I get access to the X API v2?

Apps that are associated with a Project within the developer portal will atleast have Free access to the X API v2.  In order to create a project, you must have a developer account.  Sign up for a developer account.

What are the different access levels to the X API v2?

All X API access requires a developers account, which can be created quickly by signing up.  Free access will be available immediately, and Basic and Pro access can be purchased via developer portal. Enteprise access can be requested

• Free: Free, instant access to the X API. Includes 500 Posts and 100 Reads per month and a single App environment. 1 App, 1 Project.
• Basic: $200 per month or $175 per month with annual subscription ($2,100 total), 2 Top-ups allowed and access up to 10K Posts /month, and 2 App environments.
• Pro: $5K per month or $4.500 per month with annual subscription ($54,000 total), 2 Top-ups allowed and access up to 1M Posts /month and 3 app environments.
• Enterprise: Starting at $42K per month. Includes 50+ million Posts  per month, 3+ apps. Requires an approved developer account application.
  
  

How can I apply for Enterprise access?

Apply for Enterprise access.

What are the v2 rate limits?

X API v2 endpoints each have their own technical rate limits listed on their respective API Reference, or in aggregate on the X API v2 rate limits review page. In general, the X API v2 rate limits are similar to the standard v1.1 rate limits. There is a monthly Post cap on the volume of Posts  that can be returned (consumed) with the X API v2. Apps that are in a Project with Enterprise access have different access on X API v2 endpoints. Rate limit elevations are dependent on your contract and package.

What is the monthly Post cap?

In addition to the request frequency rate limits per endpoint, there are monthly Post consumption limits that are applied across v2 endpoints used by an App at the the Project configuration level. The monthly Post cap does not deduplicate Posts  returned multiple times within the time period. The usage month can be reviewed on the dashboard, and is determined by the date your developer account was approved at 00:00 UTC. 

Endpoints that are included in the Post cap limit include: 

A Project with Free access can consume up to  500 Posts and 100 Reads per month.

A Project with Basic access can consume up to 10,000 Posts  per month.

A Project with Pro access can consume 1,000,000 Posts  per month.

A Project with Enterprise access can consume 50,000,000 Posts  per month and higher.

Does the POST limit apply to X API v2?

Developer Apps are by default limited to the number of POST requests they can create across all authenticated users. The POST limit is measured at the App level across both v1.1 and v2. More information on the POST limit is described in the announcement.

The App level POST limits are:

• Posts  & Reposts (combined): 300 per 3 hours
• Likes: 1000 per 24 hours
• Follows: 1000 per 24 hours
• Direct Messages: 15,000 per 24 hours

What is the monthly Post cap?

Post consumption by volume is set at the project level when using v2 endpoints that contribute to the consumption limit.  Posts received from the following endpoints count towards this monthly Post cap:

• Recent search: GET /2/tweets/search/recent
• Filtered stream: GET /2/tweets/search/stream
• User Post timeline: GET /2/users/:id/tweets
• User mention timeline: GET /2/users/:id/mentions
• Posts liked by user: GET /2/users/:id/liked_tweets

Which endpoints are available in Free, Basic, and Pro tiers?

All available endpoints can be found listed here.

Can I use the same X App for accessing v1.1 and v2?

Yes, all X Apps that have been configured with a Project can access v2 as well. Free, Basic, and Pro have limited access to v1.1. You can see access here. Enterprise customers have access to all v1.1 endpoints. 

How can I track my X API v2 usage?

X API v2 usage is tracked at the Project level and is shown within the developer portal dashboard.  Usage is measured and reset based on the date of the month shown within the monthly Post cap usage measurement bar.  Only certain endpoints (like filtered stream and recent search) count towards the monthly Post cap per Project.

Where can I review my v2 setup?

All setup for X API v2 is done within the developer portal. The X App you are using for v2 requests must be linked to a Project.

Will there be a v3?

It's likely that in the future, there may be a version 3 of the X API if there is an opportunity to create more functionality and access for developers to build with X, which would require a non reverse compatible (breaking) change in order to launch.  Any additive, non breaking changes will be handled within minor version releases within X API v2 and can be reviewed within the changelog here.

Frequently asked questions about X API v2 features and functionality

What is only available with X API v2?

X API v2 is a consistent API across different access levels and will follow the X Developer Platform versioning strategy. Some of the major net new features include:

In addition to the above features, we’ve also released the following functionality:

• High confidence spam filtering
• Shortened URLs are fully unwound for easier URL analysis
• Simplified JSON response objects by removing deprecated fields and modernizing labels
• Recovery and redundancy functionality for our streaming endpoints
• Return of 100% of matching public and available Posts in search queries
• Streaming "rules" so you can make changes without dropping connections
• More expressive query language for filtered stream and search
• OpenAPI spec to build new libraries & more transparently track changes
• API support for new features and endpoints more quickly as our platform evolves to meet the needs of developers, researchers, businesses, and people using X.

What is the X API v2 OpenAPI spec?

Find the spec here: https://api.x.com/2/openapi.json

Where are the v2 code examples?

Review the tools and libraries page and look for the v2 label. Also, look for the X API v2 label on Github libraries built by X or the community, and review the X API v2 postman collection.

How can I get the same v1.1 response data per Post in v2?

You can get the same v1.1 Post fields using the X API v2 if you specify the fields and expansions. For example, when making your request to the GET /tweets endpoint, use the following URI, making sure to replace the Post ID with your preferred post:

https://api.x.com/2/tweets?ids=1412865600439738368&expansions=author_id,referenced_tweets.id,referenced_tweets.id.author_id,entities.mentions.username,attachments.media_keys,in_reply_to_user_id,geo.place_id&tweet.fields=attachments,author_id,created_at,entities,geo,id,in_reply_to_user_id,lang,possibly_sensitive,public_metrics,referenced_tweets,source,text,withheld&user.fields=created_at,description,entities,id,location,name,profile_image_url,protected,public_metrics,url,username,verified,withheld&media.fields=duration_ms,height,media_key,preview_image_url,public_metrics,type,url,width&place.fields=contained_within,country,country_code,full_name,geo,id,name,place_type

Or to get all available fields in X API v2, you can request:

https://api.x.com/2/tweets?ids=1412865600439738368&expansions=author_id,referenced_tweets.id,referenced_tweets.id.author_id,entities.mentions.username,attachments.poll_ids,attachments.media_keys,in_reply_to_user_id,geo.place_id&tweet.fields=attachments,author_id,context_annotations,conversation_id,created_at,entities,geo,id,in_reply_to_user_id,lang,non_public_metrics,organic_metrics,possibly_sensitive,promoted_metrics,public_metrics,referenced_tweets,reply_settings,source,text,withheld&user.fields=created_at,description,entities,id,location,name,pinned_tweet_id,profile_image_url,protected,public_metrics,url,username,verified,withheld&media.fields=alt_text,duration_ms,height,media_key,non_public_metrics,organic_metrics,preview_image_url,promoted_metrics,public_metrics,type,url,width&place.fields=contained_within,country,country_code,full_name,geo,id,name,place_type&poll.fields=duration_minutes,end_datetime,id,options,voting_status

Will my v1.1 search queries and filters work with v2?

The syntax and structure of the search and filter API functionality has changed with v2. 

Will my authentication settings and authenticated users with v1.1 work with v2?

Yes. The authentication flow and authorization settings are the same for v1.1 and v2.  Both versions use OAuth1.0a and OAuth2 bearer token. You should not need to re-authenticate for new access tokens. 

How do X context annotations work?

X classifies Posts semantically, meaning that we curate lists of keywords, hashtags, and @handles that are relevant to a given topic. If a Post contains the text we’ve specified, it will be labeled appropriately. This differs from a machine learning approach where a model is trained specifically to classify text (in this case, Posts) and produce a probability score alongside the output/classification.

How do I know that X annotation data is complete and trustworthy?

X's annotations are curated by domain experts using research and QA processes that have been refined over the course of several years. The process is supported by custom tooling to scale data tracking as far as we are able to maintain excellent precision and recall. In addition, our data is audited regularly by an internal team, having received a precision score of ~80% for the past several quarters.

How do you ensure precision?

Team members QA our entities on a daily basis to ensure high precision and recall. Additionally, our work is audited quarterly by an internal team, which manually reviews 10,000 Posts across all of our domains to calculate a precision score.

How do you decide what to track?

For some domains, like sports and TV, we rely on automated ingest to build out our graph. In the News domain, we track data around stories published by the X Moments team. Otherwise, the team uses a variety of research methods to identify topics to track that garner a high amount of conversation on the platform.

What historical support is available with Post Annotations?

Data tracking begins the moment an entity is published; therefore, we do not annotate Posts that were published prior to a given entity being tracked. For example, if an upstart brand/company is added to the taxonomy, we will not retroactively annotate Posts about that brand prior to when the annotation was added.

What historical support is available with Post Annotations?

Data tracking begins the moment an entity is published; therefore, we do not annotate Posts that were published prior to a given entity being tracked. For example, if an upstart brand/company is added to the taxonomy, we will not retroactively annotate Posts about that brand prior to when the annotation was added.

Frequently asked questions about building to X API v2

What can I do with the X API v2?

There are several use cases for working with the X API. X developers range from those learning to code to engineering teams integrating with X for enterprise solutions. Here are some ideas for use cases:

Teach or learn valuable skills with the X API.

Build for fun, experiment, explore, and create. See more on building a X bot.

Build for people on X, to enhance and improve their experience on the platform.

Build for good, to make the world, and X, a better place.

Do reserach using the X API to get historical and real-time data points for your next research project.

Build for businesses using X'S API to help businesses listen, act and dicsover.

How can I try the X API v2 right now?

X API tools includes the X API Playground which helps you to test out several X API v2 endpoints even before signing up for an account. Get started with a simple username lookup here, or search for recent Posts with a simple keyword query here. 

I built a X bot, how do I add a bot label to the account?

To attach a label to your bot account, follow these steps:

1. Go to your account settings

2. Select “Your account”

3. Select “Automation”

4. Select “Managing account”

5. Next, select the X account, which runs your bot account

6. Enter your password to log in

7. Finally, you should see confirmation that the label has been applied to your account.

Will the account label be available as a data field in the API, or as an endpoint?

We’re considering adding this label as a data field and creating an endpoint for the future. We’re continuing to add new features and functionality. Be sure to keep an eye on our public roadmap for the latest. As always, we’d love to hear what you think. Please reach out with any questions or feedback on what you’d like to see in the future.

What if a "bad bot" adds a label to thier account? Will disciplinary action be taken?

All accounts on X are subject to the X Rules and automated accounts are governed by this policy. As the label is opt-in only, we will not be auditing accounts that choose to adopt it at this time and will rely on our reporting process should an account violate the rules.

Frequently asked questions about migration to X API v2

When should I start migrating to v2?

X API v2 is ready for production use and will only get better.  The v1.1, premium and enterprise APIs will still be supported in their current functionality, but any new features or improvements will be applied to X API v2.  To start your migration, review the migration hub and guides available here.  Or <reach out to us> to answer any questions not addressed here.

What are the differences between the X API v1.1 and v2?

Review the resoruces in the migration hub including the comparison summary for each endpoint.

Where are the migration guides?

See the format comparisons:

• Standard 1.1 to v2
• Native Enriched to v2 (premium and enterprise)
• Activity Streams to v2 (enterprise)

As well as each specific endpoint:

Will my search queries work in v2?

If you're using v1.1, you will need to update your query syntax.  Most v1.1 operators have a similar v2 operator counterpart.  To convert your v1.1 queries to v2, check out the conversion tool.

If you're using premium Search posts, you can use the same queries from premium with v2.

If you're using enterprise Search, you can use the same queries from enterprise with v2.

Will my stream filters work in v2?

If you're using statuses/filter v1.1, you will need to update your filter/parameter syntax to create filter rules for v2.  Most v1.1 operators and functionality have a similar v2 operator counterpart.  To convert your v1.1 queries to v2, check out the conversion tool.  To review filter rule migration and a list of all filter operators and functions, please see our guide here: 

If you're using enterprise PowerTrack, you can use the same filter rules from enterprise with v2.

Get support

The X community forum is available for you to ask technical questions about the X developer platform. This is a discussions forum where you will find questions by other developers and technical information on a variety of topics related to using the X API.

We encourage you to join the conversation by responding to questions and engaging in conversations on our forum. X employees are also there to provide support.

Before you post a question

• Search the X developer documentation for information relating to your issue
• Search the community forum for similar questions by other developers
• Review the community forum guidelines

When you post a question, make sure to include the following information

• A description of the problem
• The API call being made (include headers, if possible)
• The X response returned (include any error messages)
• What you expected to receive instead
• List of steps taken to troubleshoot the issue
• List of steps required to reproduce the issue
• If relevant, the time frame during which an issue occurred 
• If relevant, the App ID, post ID, etc.
• Any relevant code sample or screenshots

Please only include one topic/question per post.