Introduction

Searching for Posts is an important feature used to surface X conversations about a specific topic or event. While this functionality is present in X, these endpoints provide greater flexibility and power when filtering for and ingesting Posts so you can find relevant data for your research more easily; build out near-real-time ‘listening’ applications; or generally explore, analyze, and/or act upon Posts related to a topic of interest. 

We offer two endpoints that allow you to search for Posts: Recent search and full-archive search. Both of these REST endpoints share a common design and features, including their use of a single search query to filter for Posts around a specific topic. These search queries are created with a set of operators that match on Post and user attributes, such as message keywords, hashtags, and URLs. Operators can be combined into queries with boolean logic and parentheses to help refine the queries matching behavior. 

Both the recent search and the full-archive search endpoints provide edited Post metadata. All objects for Posts created since September 29, 2022, include Post edit metadata, even if the Post was never edited. Each time a Post is edited, a new Post ID is created. A Post's edit history is documented by an array of Post IDs, starting with the original ID.

These endpoints will always return the most recent edit, along with any edit history. Any Post collected after its 30-minute edit window will represent its final version. To learn more about Edit Post metadata, check out the Edit Posts fundamentals page.

Once you’ve set up your query and start receiving Posts, these endpoints support navigating the results both by time and Post ID ranges. This is designed to support two common use cases: 

• Get historical: Requests are for a period of interest, with no focus on the real-time nature of the data. A single request is made, and all matching data is delivered using pagination as needed. This is the default mode for Search Posts.
• Polling or listening: Requests are made in a "any new Posts since my last request?" mode. Requests are made on a continual basis, and typically there is a use case focused on near real-time 'listening' for Posts of interest.
   

Many operators and query limits are exclusive to Enterprise access, meaning that you must use keys and tokens from an App within a Project with Enterprise access to utilize the additional functionality. You can learn more about this in the endpoint sections below.

Both the recent search and the full-archive search endpoints returned Posts contribute to the monthly Post cap.

Recent search

The recent search endpoint allows you to programmatically access filtered public Posts posted over the last week, and is available to all developers who have a developer account and are using keys and tokens from an App within a Project.

You can authenticate your requests with OAuth 1.0a User Context, OAuth 2.0 App-Only, or OAuth 2.0 Authorization Code with PKCE. However, if you would like to receive private metrics, or a breakdown of organic and promoted metrics within your Post results, you will have to use OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, and pass user Access Tokens that are associated with the user that published the given content. 

This endpoint can deliver up to 100 Posts per request in reverse-chronological order, and pagination tokens are provided for paging through large sets of matching Posts. 

When using a Project with regular access, you can use the basic set of operators and can make queries up to 512 characters long. When using a Project with Enterprise access, you have access to additional operators. Projects with Enterprise Access can make queries up to 4096 characters long.

Learn more about access levels.

Full-archive search

The v2 full-archive search endpoint is only available to Projects with Pro access and Enterprise access. The endpoint allows you to programmatically access public Posts from the complete archive dating back to the first Post in March 2006, based on your search query.

You can authenticate your requests to this endpoint using OAuth 2.0 App-Only, and the App Access Token must come from an App that is within a Project that has Pro or Enterprise access. Since you cannot make a request on behalf of other users (OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE) with this endpoint, you will not be able to pull private metrics. 

This endpoint can deliver up to 500 Posts per request in reverse-chronological order, and pagination tokens are provided for paging through large sets of matching Posts.

Note: If requesting annotations through the tweet.fields parameter, the max_results parameter is currently limited to a max value of 100. This may change in the future, but please be mindful of this limitation.

Since this endpoint is only available to those that have been approved for Pro and Enterprise access, you have access to the full set of search operators and can make queries up to 1024 characters long.