Search tweets

​

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.

Account setup

To access these endpoints, you will need:

• An approved developer account.
• To authenticate using the keys and tokens from a developer App that is located within a Project. 

Learn more about getting access to the X API v2 endpoints in our getting started guide.

​

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.

​

Quick Start

​

Getting started with the recent search endpoint

This quick start guide will help you make your first request to the recent search endpoint with a set of specified fields using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

​

Steps to build a recent search request

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the Search Posts > Recent search request.

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do this with this endpoint, you must authenticate your request with either OAuth 2.0 App-Only, OAuth 2.0 Authorization Code with PKCE, or OAuth 1.0a User Context authentication methods.

For simplicity’s sake, we will utilize OAuth 2.0 App-Only with this request, but you will need to use one of the other authentication methods if you’d like to request private metrics or Posts. 

To utilize OAuth 2.0 App-Only, you must add your keys and tokens, specifically the App Access Token (also known as the App-only Bearer Token) to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

These variables will automatically be pulled into the request’s authorization tab if you’ve done this correctly.  

Step three: Create a search query

Each recent search query requires a single search query. For this example, we are going to use a query that matches on Posts posted by the @XDevelopers account. For this query we use the from operator and set it to XDevelopers (case insensitive):

from:XDevelopers

In Postman, navigate to the “Params” tab and enter this ID, or a string of Post IDs separated by a comma, into the “Value” column of the ids parameter.

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default Post object fields in your response: id , text, and  edit_history_tweet_ids. If you would like to receive additional fields beyond id , text, and edit_history_tweet_ids, you will have to specify those fields in your request with the field and/or expansion parameters.

For this exercise, we will request a four different sets of fields from different objects:

1. The default Post object fields.
2. The additional tweet.created_at field in the primary user objects.
3. The associated authors’ user object’s default fields for the returned Posts.
4. The additional  user.description field in the associated user objects.

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see the following URL next to the “Send” button:

https://api.x.com/2/tweets/search/recent?query=from:XDevelopers&tweet.fields=created_at&expansions=author_id&user.fields=created_at

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive the following response:

{
   "data": [
       {
           "author_id": "2244994945",
           "created_at": "2020-06-11T16:05:06.000Z",
           "id": "1271111223220809728",
           "text": "Tune in tonight and watch as @jessicagarson takes us through running your favorite Python package in R. 🍿\n\nLearn how to use two powerful programming languages for data science together, and see a live example that uses the recent search endpoint from Twitter’s Developer Labs. https://t.co/v178oUZNuj"
       },
       {
           "author_id": "2244994945",
           "created_at": "2020-06-10T19:25:24.000Z",
           "id": "1270799243071062016",
           "text": "As we work towards building the new Twitter API, we’ve extended the deprecation timeline for several Labs v1 endpoints. Learn more 📖 https://t.co/rRWaJYJgKk"
       },
       {
           "author_id": "2244994945",
           "created_at": "2020-06-09T18:08:47.000Z",
           "id": "1270417572001976322",
           "text": "Annotations help you learn more about a Tweet — they can even help you find topics of interest. 🔬\n\nIn this tutorial, @suhemparack shows us how find Tweets related to COVID-19 using annotations + the filtered stream endpoint.\n\nLearn how you can, too. ⤵️\nhttps://t.co/qwVOgw0zSV"
       }
   ],
   "includes": {
       "users": [
           {
               "description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API. \n\n#BlackLivesMatter",
               "id": "2244994945",
               "name": "X Developers",
               "username": "XDevelopers"
           }
       ]
   },
   "meta": {
       "newest_id": "1271111223220809728",
       "oldest_id": "1270417572001976322",
       "result_count": 3
   }
}

​

Getting started with the full-archive search endpoint

This quick start guide will help you make your first request to the full-archive search endpoint with a set of specified fields using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

​

Steps to build a full-archive search request

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the Search Posts > Full-archive search request.

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do so with this endpoint, you must authenticate your request with the OAuth 2.0 App-Only authentication methods.

You must add your keys and tokens, specifically the App Access Token (also known as the App-only Bearer Token) to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

This variable will automatically be pulled into the request’s authorization tab if you’ve done this correctly.  

Step three: Create a search query

Each full-archive search query requires a single search query. For this example, we are going to use a query that matches on Posts posted by the @XDevelopers account. For this query we use the from operator and set it to XDevelopers (case insensitive):

from:XDevelopers

In Postman, navigate to the “Params” tab and enter this ID, or a string of Post IDs separated by a comma, into the “Value” column of the ids parameter.  

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default Post object fields in your response: id ,text, and edit_history_tweet_ids. Note that if you receive Posts from before editing was supported, the edit_history_tweet_ids field will not be provided. No history backfill was performed for this field. 

If you would like to receive additional fields beyond these default fields, you will have to specify those fields in your request with the field and/or expansion parameters.

For this exercise, we will request a four different sets of fields from different objects:

1. The default Post object fields
2. The additional tweet.created_at field in the primary user objects
3. The associated authors’ user object’s default fields for the returned Posts
4. The additional user.description field in the associated user objects  

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see the following URL next to the “Send” button:

https://api.x.com/2/tweets/search/all?query=from:XDevelopers&tweet.fields=created_at&expansions=author_id&user.fields=created_at

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive a response similar to the following:

{
   "data": [
       {
           "author_id": "2244994945",
           "created_at": "2020-06-11T16:05:06.000Z",
           "id": "1271111223220809728",
           "text": "Tune in tonight and watch as @jessicagarson takes us through running your favorite Python package in R. 🍿\n\nLearn how to use two powerful programming languages for data science together, and see a live example that uses the recent search endpoint from Twitter’s Developer Labs. https://t.co/v178oUZNuj"
       },
       {
           "author_id": "2244994945",
           "created_at": "2020-06-10T19:25:24.000Z",
           "id": "1270799243071062016",
           "text": "As we work towards building the new Twitter API, we’ve extended the deprecation timeline for several Labs v1 endpoints. Learn more 📖 https://t.co/rRWaJYJgKk"
       },
       {
           "author_id": "2244994945",
           "created_at": "2020-06-09T18:08:47.000Z",
           "id": "1270417572001976322",
           "text": "Annotations help you learn more about a Tweet — they can even help you find topics of interest. 🔬\n\nIn this tutorial, @suhemparack shows us how find Tweets related to COVID-19 using annotations + the filtered stream endpoint.\n\nLearn how you can, too. ⤵️\nhttps://t.co/qwVOgw0zSV"
       }
   ],
   "includes": {
       "users": [
           {
               "description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API. \n\n#BlackLivesMatter",
               "id": "2244994945",
               "name": "Twitter Dev",
               "username": "TwitterDev"
           }
       ]
   },
   "meta": {
       "newest_id": "1271111223220809728",
       "oldest_id": "1270417572001976322",
       "result_count": 3
   }
}

In this example, we used a very simple query. If you would like to see more detailed guides, please visit the resources listed below. 

​

How to integrate with the Search Posts endpoints

This page contains information on several tools and key concepts that you should be aware of as you integrate the recent search or full archive search endpoints into your system. We’ve split the page into the following sections:

• Helpful tools
• Key concepts

  • Authentication

  • Developer portal, Projects, and Apps

  • Rate limits

  • Fields and expansions

  • Metrics

  • Building search queries

  • Pagination

  • Post caps 

  • Post edits 

​

Helpful tools

Before we start to explore some key concepts, we recommend that you use one of the following tools or code samples to start testing the functionality of these endpoints.

​

Code samples

Interested in getting set up with these endpoints with some code in your preferred coding language? We’ve got a handful of different code samples available that you can use as a starting point on our GitHub page, including a Python client and a Ruby client.

​

Libraries

Take advantage of one of our many community third-party libraries to help you get started. You can find a library that works with the v2 endpoints by looking for the appropriate version tag.

​

Postman

Postman is a great tool that you can use to test out these endpoints. Each Postman request includes all of the given endpoint’s parameters to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our Using Postman page.  

​

Key concepts

​

Authentication

All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, OAuth 2.0 App-Only, or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to the recent search endpoint. You must use OAuth 2.0 App-Only when using the full archive search endpoint.

OAuth 2.0 App-Only just requires that you pass an OAuth 2.0 App Access Token with your request. You can either generate an App Access Token from directly within a developer App, or generate one using the POST oauth2/token endpoint.

OAuth 1.0a User Context requires you to utilize your API Keys, user Access Tokens, and a handful of other parameters to create an authorization header, which you will then pass with your request. The Access Tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the 3-legged OAuth flow. 

Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a library, use a tool like Postman, or use OAuth 2.0 to authenticate your requests. If you would like to request a Post or private metrics from these endpoints, you will need to use a either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, which will ensure that you have the proper permissions from the user that owns that content.

OAuth 2.0 Authorization Code with PKCE allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. 

To enable OAuth 2.0 in your App, you must enable it in your’s App’s authentication settings found in the App settings section of the developer portal.

​

Developer portal, Projects, and developer Apps

To work with any X API v2 endpoints, you must have signed up for a developer account, set up a Project within that account, and created a developer App within that Project. Your keys and tokens within that developer App will work for these search endpoints.

You can use keys and tokens from a Project with any access level to make requests to the recent search endpoint. However, you will need to use Project with the Pro or Enterprise access level to make requests to the full archive search endpoint. If you have Enterprise access, you will have access to additional functionality, including the availability of additional operators and longer query lengths.  

​

Rate limits

Every day, many thousands of developers make requests to the X API. To help manage the volume, rate limits are placed on each endpoint that limits the number of requests that every developer can make on behalf of an app or on behalf of an authenticated user.

There are different rate limits applied for these endpoints depending on which authentication method is being used. The app-level rate limits apply to an App making requests using OAuth 2.0 App-Only, whereas the user-level rate limit applies to requests being made on behalf of the specific authorizing user using OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE. These two rate limits are based on the frequency of requests within a 15-minute window.

For example, an app using OAuth 2.0 App-Only auth to make requests to the recent search endpoint can make 450 requests (including pagination requests) within a 15-minute timeframe. That same app, within the same 15-minute timeframe and with two different authenticated users (using OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE) can make up to 180 requests (including pagination requests) to the recent search endpoint for each authenticated user.  

​

Fields and expansions

The X API v2 allows you to select exactly which data you want returned from the API using fields and expansions. The expansion parameter allows you to expand objects referenced in the payload. For example, this endpoint allows you to request poll, place, media, and other objects using the expansions parameter.

The fields parameters allows you to select exactly which fields within the different data objects you would like to receive. By default, the primary Post object returned by these endpoints include the id and text fields (in addition to edit_history_tweet_ids for Posts created after that feature was launched). To receive additional fields such as author_id or public_metrics, you will have to specifically request those using the fields parameters. Some important fields that you may want to consider using in your integration are our poll data, metrics, Post annotations, and conversation ID fields.

We’ve added a guide on how to use fields and expansions together to our X API v2 data dictionary.  

​

Metrics

The X API v2 endpoints allow you to request metrics directly from the returned objects, assuming you pass the proper fields with your request.

There are some limitations with Post metrics that you should be aware of, specifically related to user privacy and the following response fields:

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics
• media.fields.non_public_metrics
• media.fields.promoted_metrics
• media.fields.organic_metrics

The noted fields include private metrics data, meaning you must be authorized by the Post’s publisher to retrieve this data on their behalf when using the recent search endpoint, meaning you must use OAuth 1.0a User Context. Since you can only use this authentication method using recent search, you will not be able to retrieve these metrics via the full archive search endpoint.

For example, in order to receive non_public_metrics for user ID 1234’s Posts, you will need to include access tokens associated with that user in your request. You can have users authorize your app and receive a set of access tokens associated with them by using the 3-legged OAuth flow.

All non_public_metrics, organic_metrics, and promoted_metrics are only available for Posts created in the last 30 days. This means that when you are requesting the noted fields, the results will automatically adjust to only include Posts from the last 30 days.

If these noted fields are requested, only Posts that are authored by the authenticated user will be returned, all other Posts will receive an error message.  

​

Building search queries

The central feature of these endpoints is their use of a single search query to filter the Posts that deliver to you. These queries are made up 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 query’s matching behavior.

You can use our guide on how to build a query to learn more.

We have also written a more in-depth tutorial on how to [build high-quality filters for getting X data]https://developer.x.com/en/docs/tutorials/building-high-quality-filters.  

​

Pagination

These endpoints utilize pagination so that responses are returned quickly. In cases where there are more results than what can be sent in a single response (up to 100 Posts for recent search and 500 for full-archive search) you will need to paginate. Use the max_results parameter to identify how many results will return per page, and the pagination_token parameter to return the next page of results. You can learn more by reviewing our pagination guide.

​

Post caps

The Search Posts endpoints are limited in the number of Posts that they can return in a given month, regardless of pagination.

Regardless of which search endpoint you use, the Posts returned will count towards the Project-level Post caps. Usage is shown in the developer portal, and the ‘month’ starts on your subscription renewal day shown on the developer portal dashboard.

Post edits

Posts that are eligible for edits can be edited up to five times in the 30 minutes after the original Post was published. The search endpoints will always provide the latest version of the Post. If you only request Posts that were published 30 or more minutes ago, you will always receive the final version of the Post. However, if you have a near-real-time use case, and are querying Posts published within the last thirty minutes, those Posts could have been edited after you received them. These Posts can be rehydrated with search, or the Post Lookup endpoint to confirm their final state. To learn more about how Post edits work, see the Post edits fundamentals page.  

​

Building queries for Search Posts

The search endpoints accept a single query with a GET request and return a set of historical Posts that match the query.  Queries are made up of operators that are used to match on a variety of Post attributes. 

To learn more about how to create high-quality queries, visit the following tutorial: [Building high-quality filters for getting X data]https://developer.x.com/en/docs/tutorials/building-high-quality-filters

​

Table of contents

• Building a query
• Query limitations
• Operator availability
• Operator types: standalone and conjunction-required
• Boolean operators and grouping
• Order of operations
• Punctuation, diacritics, and case sensitivity
• Specificity and efficiency
• Quote Tweet matching behavior
• Iteratively building a query
• Adding a query to your request
• Query examples
• List of operators

​

Building a query

​

Query limitations

Your queries will be limited depending on which access level you are using. 

If you have Basic or Pro access, your query can be 512 characters long for recent search endpoint. 

If you have Pro access, your query can be 1,024 characters long for full archive search endpoint. 

​

Operator availability

While most operators are available to any developer, there are several that are reserved for certain access levels. We list which access level each operator is available to in the list of operators table using the following labels:

• Core operators: Available when using any Project.
• Advanced operators: Available when using a Project with certain access level

​

Operator types: standalone and conjunction-required

Standalone operators can be used alone or together with any other operators (including those that require conjunction).

For example, the following query will work because it uses the #hashtag operator, which is standalone:

#xapiv2

Conjunction-required operators cannot be used by themselves in a query; they can only be used when at least one standalone operator is included in the query. This is because using these operators alone would be far too general, and would match on an extremely high volume of Posts.

For example, the following queries are not supported since they contain only conjunction-required operators:

has:media has:links OR is:retweet

If we add in a standalone operator, such as the phrase “X data”, the query would then work properly. 

“X data” has:mentions (has:media OR has:links)

​

Boolean operators and grouping

If you would like to string together multiple operators in a single query, you have the following tools at your disposal:

A note on negations

The operators -is:nullcast must always be negated.

Negated operators cannot be used alone.

Do not negate a set of operators grouped together in a set of parentheses. Instead, negate each individual operator. For example, instead of using skiing -(snow OR day OR noschool), we suggest that you use skiing -snow -day -noschool. 

​

Order of operations

When combining AND and OR functionality, the following order of operations will dictate how your query is evaluated.

1. Operators connected by AND logic are combined first
2. Then, operators connected with OR logic are applied

For example:

• apple OR iphone ipad would be evaluated as apple OR (iphone ipad)
• ipad iphone OR android would be evaluated as (iphone ipad) OR android

To eliminate uncertainty and ensure that your query is evaluated as intended, group terms together with parentheses where appropriate. 

For example:

• (apple OR iphone) ipad
• iphone (ipad OR android)  

​

Punctuation, diacritics, and case sensitivity

If you specify a keyword or hashtag query with character accents or diacritics, it will match Post text that contains both the term with the accents and diacritics, as well as those terms with normal characters. For example, queries with a keyword Diacrítica or hashtag #cumpleaños will match Diacrítica or #cumpleaños, as well as with Diacritica or #cumpleanos without the tilde í or eñe.

Characters with accents or diacritics are treated the same as normal characters and are not treated as word boundaries. For example, a query with the keyword cumpleaños would only match activities containing the word cumpleaños and would not match activities containing cumplea, cumplean, or os.

All operators are evaluated in a case-insensitive manner. For example, the query cat will match Posts with all of the following: cat, CAT, Cat.

The filtered stream matching behavior acts differently from Search Posts. When building a filtered stream rule, know that keywords and hashtags that include accents and diacritics will only match on terms that also include the accent and diacritic, and will not match on terms that use normal characters instead. 

For example, filtered stream rules that include a keyword Diacrítica or hashtag #cumpleaños will only match the terms Diacrítica and #cumpleaños, and will not match on Diacritica or #cumpleanos without the tilde í or eñe

​

Specificity and efficiency

When you start to build your query, it is important to keep a few things in mind.

• Using broad, standalone operators for your query such as a single keyword or #hashtag is generally not recommended since it will likely match on a massive volume of Posts. Creating a more robust query will result in a more specific set of matching Posts, and will hopefully reduce the amount of noise in the payload that you will need to sift through to find valuable insights. 
  • For example, if your query was just the keyword happy you will likely get anywhere from 200,000 - 300,000 Posts per day.
  • Adding more conditional operators narrows your search results, for example (happy OR happiness) place_country:GB -birthday -is:retweet
• Writing efficient queries is also beneficial for staying within the characters query length restriction. The character count includes the entire query string including spaces and operators.
  • For example, the following query is 59 characters long: (happy OR happiness) place_country:GB -birthday -is:retweet

​

Quote Tweet matching behavior

When using the Search Posts endpoints, operators will not match on the content from the original Post that was quoted, but will match on the content included in the Quote Tweet.

However, please note that filtered stream will match on both the content from the original P that was quoted and the Quote Tweet’s content.  

​

Iteratively building a query

Test your query early and often

Getting a query to return the “right” results the first time is rare. There is so much on X that may or may not be obvious at first and the query syntax described above may be hard to match to your desired search. As you build a query, it is important for you to periodically test it out.

For this section, we are going to start with the following query and adjust it based on the results that we receive during our test: 

happy OR happiness

Use results to narrow the query

As you test the query, you should scan the returned Posts to see if they include the data that you are expecting and hoping to receive. Starting with a broad query and a superset of Post matches allows you to review the result and narrow the query to filter out undesired results.  

When we tested the example query, we noticed that we were getting Po in a variety of different languages. In this situation, we want to only receive Posts that are in english, so we’re going to add the lang: operator:

(happy OR happiness) lang:en

The test delivered a number of Posts wishing people a happy birthday, so we are going to add -birthday as a negated keyword operator. We also want to only receive original Posts, so we’ve added the negated -is:retweet operator:

(happy OR happiness) lang:en -birthday -is:retweet

Adjust for inclusion where needed

If you notice that you are not receiving data that you expect and know that there are existing Posts that should return, you may need to broaden your query by removing operators that may be filtering out the desired data. 

For our example, we noticed that there were other Posts in our personal timeline that expressed the emotion that we are looking for and weren’t included in the test results. To ensure we have greater coverage, we are going to add the keywords, excited and elated.

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet

Adjust for popular trends/bursts over the time period

Trends come and go on X quickly. Maintaining your query should be an active process. If you plan to use a query for a while, we suggest that you periodically check in on the data that you are receiving to see if you need to make any adjustments.

In our example, we notice that we started to receive some Posts that are wishing people a “happy holidays”. Since we don’t want these Posts included in our results, we are going to add a negated -holidays keyword.

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays 

​

Adding a query to your request

To add your query to your request, you must use the query parameter. As with any query parameters, you must make sure to HTTP encode the query that you developed.

Here is an example of what this might look like using a cURL command, with an additional tweet.fields and max_results parameter included. If you would like to use this command, please make sure to replace $BEARER_TOKEN with your own Bearer Token:

curl https://api.x.com/2/tweets/search/recent?query=cat%20has%3Amedia%20-grumpy&tweet.fields=created_at&max_results=100 -H "Authorization: Bearer $BEARER_TOKEN"

​

Query examples

​

Tracking a natural disaster

The following query matched on original Posts coming from weather agencies and gauges that discuss Hurricane Harvey, which hit Houston in 2017.

Here is what the query would look like without the HTTP encoding:

has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet

And here is what the query would look like with the HTTP encoding, the query parameter, and the recent search URI:

https://api.x.com/2/tweets/search/recent?query=-is%3Aretweet%20has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC\_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS\_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1)

​

Reviewing the sentiment of a conversation

The next rule could be used to better understand the sentiment of the conversation developing around the hashtag, #nowplaying, but scoped to just Posts published within North America.

Here is what the two different queries, one for positive and one for negative, would look like without the HTTP encoding:

#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing

#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible

And here is what the query would look like with the HTTP encoding, the query parameter, and the recent search URI:

https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing

https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible

​

Find Posts that relate to a specific Post annotation

This rule was built to search for original Posts that included an image of a pet that is not a cat, where the language identified in the Post is Japanese. To do this, we used the context: operator to take advantage of the Post annotation functionality. We first used the Post lookup endpoint and the tweet.fields=context_annotations fields parameter to identify which domain.entity IDs we need to use in our query:

• Posts that relate to cats return domain 66 (Interests and Hobbies category) with entity 852262932607926273 (Cats). 
• Posts that relate to pets return domain 65 (Interests and Hobbies Vertical) with entity 852262932607926273 (Pets). 

Here is what the query would look like without the HTTP encoding:

context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja

And here is what the query would look like with the HTTP encoding, the query parameter, and the recent search URI:

https://api.x.com/2/tweets/search/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja

Try out the query builder tool for additional support. 

​

Operators

​

Operator Guide

The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

​

Recent search pagination

​

Introduction

Search queries typically match on more Posts than can be returned in a single API response. When that happens, the data is returned in a series of ‘pages’. Pagination refers to methods for requesting all of the pages in order to retrieve the entire data set.

Here are fundamental recent search pagination details:

• The recent search endpoints will respond to a query with at least one page, and provide a next_token in its JSON response if additional pages are available. To receive matching Posts, this process can be repeated until no token is included in the response.

• The next_token does not expire. Multiple requests using the same next_token value will receive the same results, regardless of when the request is made.

• Posts are delivered in reverse-chronological order, in the UTC timezone. This is true within individual pages, as well as across multiple pages: 

  • The first Post in the first response will be the most recent one matching your query.
  • The last Post in the last response will be the oldest one matching your query.

• The max_results request parameter enables you to configure the number of Posts returned per response. This defaults to 10 Posts and has a maximum of 100. 

• Every pagination implementation will involve parsing next_tokens from the response payload, and including them in the ‘next page’ search request. See below for more details on how to construct these ‘next page’ requests.  

The recent search endpoint was designed to support two fundamental use patterns:

• Get historical - Requesting matching Posts from a time period of interest. These are typically one-time requests in support of historical research. Search requests can be based on start_time and end_time request parameters. recent search endpoint respond with Posts delivered in reverse-chronological order, starting with the most recent matching Post. 

• Polling - Requesting matching Posts that have been posted since the last Post received. These use cases often have a near-real-time focus and are characterized by frequent requests, “listening” for new Posts of interest. The recent search endpoint provide the since_id request parameter in support of the ‘polling’ pattern. To help with navigating by Post IDs, the until_id request parameter is also available.  

Next, we’ll discuss the historical mode. This is the default mode of the recent search endpoint and illustrates the fundamentals of pagination. Then we’ll discuss examples of polling use cases. When polling triggers pagination, there is an additional step to manage search requests.  

​

Retrieving historical data

This section outlines how you can retrieve Posts from a period of interest (currently limited to the last seven days) using the start_time and end_time request parameters. Historical requests are typically one-time requests in support of research and analysis. 

Making requests for a period of data is the default mode of the recent search endpoint. If a search request does not specify a start_time, end_time, or since_id request parameter, the end_time will default to “now” (actually 30 seconds before the time of query) and the start_time will default to seven days ago.

The endpoint will respond with the first ‘page’ of Posts in reverse-chronological order, starting with the most recent Post. The response JSON payload will also include a next_token if there are additional pages of data. To collect the entire set of matching Posts, regardless of the number of pages, requests are made until no next_token is provided. 

For example, here is an initial request for Posts with the keyword snow from the last week:

https://api.x.com/2/tweets/search/recent?query=snow

The response includes the most recent 10 Posts, along with these “meta” attributes in the JSON response:

"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }

To retrieve the next 10 Posts, this next_token is added to the original request. The request would be:

https://api.x.com/2/tweets/search/recent?query=snow&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql

The process of looking for a next_token and including it in a subsequent request can be repeated until all (or some number of) Posts are collected, or until a specified number of requests have been made. If data fidelity (collecting all matches of your query) is key to your use case, a simple “repeat until request.next_token is null” design will suffice.   

​

Polling and listening use cases

This section outlines how you can retrieve recent Posts by polling the recent search endpoint with the since_id request parameter. 

With polling use cases, “any new Posts of interest?” queries are made on an on-going, frequent basis. Unlike historical use cases, that base requests on time, polling use cases typically base requests on Post IDs.

Central to the polling use pattern is that every new Post has a unique ID that is ‘emitted’ from the X platform generally in ascending order. If one Post has an ID smaller than another, it means it was posted earlier.

The recent search endpoint support navigating the Post archive by Post ID. Responses from the endpoint include oldest_id and newest_id Post IDs. In the polling mode, requests are made with the since_id set to the largest/newest ID received so far. 

For example, say a query for new Posts about snow is made every five minutes, and the last Post we received had a Post ID of 10000. When it is time to poll, the request looks like:

https://api.x.com/2/tweets/search/recent?query=snow&since_id=10000

Next, let’s say seven Posts were posted since our last request. Since all of these fit on a single data ‘page’, there is no next_token. The response provides the Post ID of the most recent (newest) Post:

"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }

To make the next polling query, this newest_id value is used to set the next since_id parameter:

https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000

When there is more data available, and next tokens are provided, only th newest_id value from the first page of results is needed. Each page of data will include newest_id and oldest_id values, but the value provided in the first page is the only one needed for the next, regularly scheduled, polling request. So, If you are implementing a polling design, or searching for Posts by ID range, pagination logic is slightly more complicated. 

Now say that there are now 18 more matching Posts. The endpoint would respond with this initial response with a full data page and a next_token for requesting the next page of data from this five minute period. It would also include the newest Post ID need for the next polling interval in five minutes.  

"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }

To collect all the matching data for this five minute period, pass the next_token in your next request, along with the same since_id value as the previous request.

https://api.x.com/2/tweets/search/recent?query=snow&since\_id=12000&next\_token=fnsih9chihsnkjbvkjbsc

"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }

This second response provides the remaining eight Posts, and no next_token. Note that we do not update our newest_id value (12300), and instead base our next since_id request on the first response’s newest_id value:

https://api.x.com/2/tweets/search/recent?query=snow&since_id=13800

​

Comparing X API’s Search Posts endpoints

The v2 Search Tweets endpoint will eventually replace the standard v1.1 search/posts endpoint and enterprise Search API. If you have code, apps, or tools that use an older version of a X search endpoint and are considering migrating to the newer X API v2 endpoints, then this guide is for you. 

This page contains three comparison tables:

• Recent search
• Full-archive search
• Filtering operator comparison

​

Recent search comparison

The following table compares the various types of recent search endpoints:

​

Full-archive search comparison

The following table compares the various types of full-archive search endpoints:

Filtering operator comparison

The four different versions (standard, enterprise, and v2) of search Posts differ in which operators are available, and also have varying levels of operator availability within each version, which are explained below. 

Enterprise

• There are no sub-tiers of enterprise operators  

X API v2

• **Free: **Available when using any Project
• Basic: Available when using any Project
• Pro: Available when using a Project 
• Enterprise: Available when using a Project 

You can learn more about each of these sets of operators in their respective guides:

• Enterprise operators
• X API v2 operators  

Now that we understand the different operator levels within X API v2, here is the table that maps out operator availability for search Posts (note that if the cell is left blank, the operator is not available):

Other migration resources

X API migration hub

Check out some sample code for these endpoints

Search Posts: Standard v1.1 to X API v2

Search Posts: Enterprise to X API v2

​

Standard v1.1 compared to X API v2

If you have been working with the v1.1 search/posts, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 search Posts endpoint.

• Similarities
  • OAuth 1.0a User Context and OAuth 2.0 App-Only
  • Support for Post edit history and metadata. 
• Differences

  • Endpoint URLs

  • App and Project requirements

  • Response data format

  • Request parameters

  • New query operators

  • AND / OR operator precedence 

​

Similarities

OAuth 1.0a User Context and OAuth 2.0 App-Only authentication

The v1.1 search/posts and the X API v2 recent search endpoint support both OAuth 1.0a User Context and OAuth 2.0 App-Only. 

Therefore, if you were previously using the standard v1.1 search endpoint you can continue using the same authentication method if you migrate to the X API v2 version. 

Depending on your authentication library/package of choice, App-Only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App Access Token see this OAuth 2.0 App-Only guide. 

If you would like to take advantage of the ability to pull private or advertising metrics with the X API v2 endpoint, you will need to use OAuth 1.0a User Context, and pass the user access tokens related to the user who posted the Post for which you would like to pull metrics. 

Support for Post edit history and metadata

Both versions provide metadata that describes any edit history. Check out the search API References and the Post edits fundamentals page for more details. 

​

Differences

Endpoint URLs

• Standard v1.1 endpoints:

  • https://api.x.com/1.1/search/tweets

• X API v2 endpoint:

  • https://api.x.com/2/tweets/search/recent  

App and Project requirements

The X API v2 endpoints require that you use credentials from a developer App that is associated to a Project when authenticating your requests. All X API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a Project. 

Response data format

One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload.

For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload.

The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you will need to use the fields and expansions parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an includes object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object. 

We encourage you to read more about these new parameters in their respective guides, or by reading our guide on how to use fields and expansions. 

We have also put together a data format migration guide which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.   

In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and user objects.

• At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. 
• Instead of referring to Retweeted and Quoted “statuses”, X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. 
• Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like. 
• X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values.   

We also introduced a new set of fields to the Post object including the following:

• A conversation_id field
• Two new annotations fields, including context and entities
• Several new metrics fields 
• A new reply_setting field, which shows you who can reply to a given Post

​

Request parameters

The following standard v1.1 request parameters have equivalents in X API v2:

There are also a set of standard search Posts request parameters not supported in X API v2:

Here is an example request that shows the difference between a Standard request and a Search Posts request:

These requests will both return the 50 most recent Posts that contain the keyword snow. The v2 request will return the default id and text fields of the matching Posts. Here is an example of specifying additional Posts and user fields to include in the JSON payload:

New query operators

Search Posts introduces new operators in support of two new X API v2 features: 

• Conversation IDs - As conversations unfold on X, a conservation ID will be available to mark Posts that are part of the conversation. All Posts in the conversation will have their conversation_id set to the Post ID that started it. 
  • conversation_id:
• X Annotations provide contextual information about Posts, and include entity and context annotations. Entities are comprised of people, places, products and organizations. Contexts are domains, or topics, that surfaced entities are a part of. For example, people mentioned in a Post may have a context that indicates whether they are an athlete, actor, or politician.  

  • context: matches on Posts that have been annotated with a context of interest. 

  • entity: matches on Posts that have been annotated with an entity of interest. 

     

​

AND / OR operator precedence 

The basic building block for building search queries is the use of OR and AND logical groupings. The standard search API applies ORs before ANDs, while Search Posts endpoints (as well as the premium and enterprise versions) applies ANDs before ORs. This difference is critical when translating queries between the two. 

For example, with standard search, if you wanted to match Posts with the keyword ‘storm’ that mention the word ‘colorado’ or the #COwx hashtag, you could do that with the following search query:

storm #COwx OR colorado

With the Search Posts operator precedence, ANDs are applied before ORs. So the above query is equivalent to: 

(storm #COwx) OR colorado

However, the above rule would match on any Posts that mentions ‘Colorado’, regardless if the Post mentions ‘storm’ or the #COwx hashtag. In addition it would also  match Posts that mentioned both the keyword ‘storm’ and the #COwx hashtag. 

To make the query behave as originally intended, the OR clauses need to be grouped together. The translation of the original standard query to Search Posts would be:  

storm (#COwx OR colorado)

These two rules have very different matching behavior. For the month of October 2019, the original rule matches over 1,175,000 Posts while the correctly translated rule matches around 5,600 Posts. Be sure to mind your ANDs and ORs, and use parentheses where needed. 

​

cURL requests

The following section displays cURL requests for the standard v1.1 endpoint and its equivalent endpoint in v2.

The requests are made using [OAuth 2.0 App-Only](https://developer.twitter.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token). In order to run the following cURL requests, you will need to replace ACCESS_TOKEN in the authorization header with your app access token. For v2 endpoints, your app access token must belong to a developer App within a Project. 

The response payload returned by the v1.1 endpoint will be different from the response payload returned by the v2 endpoint. With v2, the response will include the default fields, as well as any other fields requested with the fields and expansions parameters. You can use these parameters to request a different set of fields to be returned.

Standard v1.1 GET search/tweets and v2 GET tweets/search/recent endpoints

curl --request GET \
--url 'https://api.x.com/1.1/search/tweets.json?q=from%3ATwitterDev%20-is%3Aretweet&count=100' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

curl --request GET \
--url 'https://api.x.com/2/tweets/search/recent?query=from%3ATwitterDev%20-is%3Aretweet&tweet.fields=created_at%2Cconversation_id%2Centities&max_results=100' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

​

Enterprise compared to X API v2

Similarities

• Pagination
• Timezone
• Support for Post edit history and metadata. 

Differences

• Endpoint URLs
• App and Project requirement
• Available time periods
• Response data format
• HTTP methods
• Request time formats
• Request parameters
• Filtering operators

​

Similarities

Pagination

While v2 has additional pagination features (new pagination parameters that allow you to navigate using Post IDs with since_id and until_id), both enterprise and v2 allow you to paginate using time (fromDate and toDate with enterprise, and start_time and end_time for v2).  

Timezone

As noted in the pagination section, you can navigate different pages of data using time for both enterprise and v2. In both cases, you will be using UTC as the timezone when using these parameters.

Support for Post edit history and metadata

Both versions provide metadata that describes any edit history. Check out the search API References and thePost edits fundamentals page for more details. 

​

Differences

Endpoint URLs

• Enterprise endpoints:
  • 30 day - http://gnip-api.x.com/search/30day/accounts/:account_name/:label.json
  • Full-archive - http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label.json
• X API v2 endpoints
  • Recent (7 day) - https://api.x.com/2/tweets/search/recent
  • Full-archive - https://api.x.com/2/tweets/search/all

App and Project requirement

The X API v2 endpoints require that you use credentials from a Project when authenticating your requests. All X API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a Project.  

Available time periods

Both the enterprise API and X API v2 offer endpoints that allow you to retrieve filtered Post data for the full-archive of Posts.

However, the X API v2 does not offer a 30 day time period endpoint like the enterprise API does. Instead it offers the aforementioned full-archive, or a 7 day time period, which align with the Native Enriched to v2 and Activity Streams to v2 which can help you map enterprise fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  

Response data format

One of the biggest differences between the enterprise response format andX API v2’s format is how you select which fields return in your payload.

For the enterprise Search API, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload.

The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you will need to use the fields and expansions parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an includes object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object.

We encourage you to read more about these new parameters in their respective guides, or by reading our guide on how to use fields and expansions.

In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and user objects.

• At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.
• Instead of referring to Retweeted and Quoted “statuses”, X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.
• Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.
• X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values.  

We also introduced a new set of fields to the Post object including the following:

• A conversation_id field
• Two new annotations fields, including context and entities
• Several new metrics fields
• A new reply_setting field, which shows you who can reply to a given Post  

And one last note. The premium response includes a requestParameters object at the root level, which contains the parameters that you included in your request. The v2 version instead contains a meta object that lives at the root level which includes the newest_id, oldest_id, result_count, and next_token if there is an additional page of results.

HTTP methods

The enterprise version of the API allows you to pass the request as either a POST HTTP method with a JSON body, or a GET HTTP method with a query string.

V2 only allows you to use the GET HTTP method with a query string.  

Request time formats

The enterprise version of this endpoint uses the following date/time format in both the pagination parameters and the timePeriod response field: YYYYMMDDHHmm

The v2 endpoint uses ISO 8601/RFC 3339 date/time format in both the pagination parameters and the start and end response fields: YYYY-MM-DDTHH:mm:ssZ  

Request parameters

The following is a table of the request parameters for enterprise and X API v2:

Filtering operators

While the operators between enterprise and X API v2 are mostly the same, there are some differences in operator availability and some new operators that were introduced to just the X API v2 version.

To see a full table of the operators that are available for X API v2, enterprise, and even premium and standard, please visit the Search Posts migration landing page.

​

API reference index

For a complete API reference, please select an endpoint from below.

​

Recent search

​

Full-archive search

Only available to those with Pro and Enterprise access

​

GET /2/tweets/search/recent

The recent search endpoint returns Tweets from the last seven days that match a search query.

The Tweets returned by this endpoint count towards the Project-level Tweet cap.

Run in Postman ❯

Try a live request ❯

Build request with API Explorer ❯

​

Endpoint URL

https://api.x.com/2/tweets/search/recent

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const recentSearch =
      await twitterClient.tweets.tweetsRecentSearch({
        //One query/rule/filter for matching Tweets. Refer to https://t.co/rulelength to identify the max query length
        query: "(from:TwitterDev) new -is:retweet",
      });
    console.dir(recentSearch, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default Fields
• Optional Fields

{
  "data": [
    {
      "id": "1373001119480344583",
      "edit_history_tweet_ids": [
        "1373001119480344583"
      ],
      "text": "Looking to get started with the Twitter API but new to APIs in general? @jessicagarson will walk you through everything you need to know in APIs 101 session. She’ll use examples using our v2 endpoints, Tuesday, March 23rd at 1 pm EST.nnJoin us on Twitchnhttps://t.co/GrtBOXyHmB"
    },
    {
      "id": "1372627771717869568",
      "edit_history_tweet_ids": [
        "1372627771717869568"
      ],
      "text": "Thanks to everyone who joined and made today a great session! 🙌 nnIf weren't able to attend, we've got you covered. Academic researchers can now sign up for office hours for help using the new product track. See how you can sign up, here 👇nhttps://t.co/duIkd27lPx https://t.co/AP9YY4F8FG"
    },
    {
      "id": "1367519323925843968",
      "edit_history_tweet_ids": [
        "1367519323925843968"
      ],
      "text": "Meet Aviary, a modern client for iOS 14 built using the new Twitter API. It has a beautiful UI and great widgets to keep you up to date with the latest Tweets. https://t.co/95cbd253jK"
    },
    {
      "id": "1366832168333234177",
      "edit_history_tweet_ids": [
        "1366832168333234177"
      ],
      "text": "The new #TwitterAPI provides the ability to build the Tweet payload with the fields that you want. nnIn this tutorial @suhemparack explains how to build the new Tweet payload and how it compares with the old Tweet payload in v1.1 👇 https://t.co/eQZulq4Ik3"
    },
    {
      "id": "1364984313154916352",
      "edit_history_tweet_ids": [
        "1364984313154916352"
      ],
      "text": "“I was heading to a design conference in New York and wanted to meet new people,” recalls @aaronykng, creator of @flocknet. “There wasn't an easy way to see all of the designers in my network, so I built one.” Making things like this opened the doors for him to the tech industry."
    },
    {
      "id": "1364275610764201984",
      "edit_history_tweet_ids": [
        "1364275610764201984"
      ],
      "text": "If you're newly approved for the Academic Research product track, our next stream is for you.nnThis Thursday, February 25th at 10AM PST @suhemparack will demo how academics can use this track to get started with the new #TwitterAPInnJoin us on Twitch! 👀nhttps://t.co/SQziibOD9P"
    }
  ],
  "meta": {
    "newest_id": "1373001119480344583",
    "oldest_id": "1364275610764201984",
    "result_count": 6
  }
}

​

Response fields

​

GET /2/tweets/search/all

The full-archive search endpoint returns the complete history of public Tweets matching a search query; since the first Tweet was created March 26, 2006.

The Tweets returned by this endpoint count towards the Project-level Tweet cap.

​

Endpoint URL

https://api.x.com/2/tweets/search/all

​

Authentication and rate limits

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const fullArchiveSearch =
      await twitterClient.tweets.tweetsFullarchiveSearch({
        //One query/rule/filter for matching Tweets. Refer to https://t.co/rulelength to identify the max query length
        query: "(from:TwitterDev) new -is:retweet",
      });
    console.dir(fullArchiveSearch, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

​

Response fields