> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get historical Posts with full-archive search

> Step-by-step tutorial for retrieving historical Posts back to 2006 using the X API v2 full-archive search endpoint, query operators, and pagination.

## Introduction

The [Search Posts endpoints](/x-api/posts/search/introduction)
in the v2 world enable you to receive Posts related to topics of interest,
based on a search query that you produce. We have two different endpoints
available with v2 Search Posts: recent search, which is available to all
developers with an approved account and can search for Posts up to seven days
old, and full-archive search, which is only available to
researchers approved for the
[Academic Research product track](https://developer.x.com/en/products/x-api/early-access/guide#na_2),
and can search through the entire archive of Posts dating back to March 2006.

You can see our full search offering on our
[search overview page](/x-api/posts/search/introduction).

These Search Posts endpoints address one of the most common use cases for
academic researchers, who might use this for longitudinal studies, or analyzing
a past topic or event.

This tutorial provides a step-by-step guide for researchers who wish to use the
full-archive search endpoint to search the complete history of public X
data. It will also demonstrate the different ways to build a dataset, such as by
retrieving geo-tagged Posts, and how to page through the available Posts for a
query.

### Prerequisites

Currently, this endpoint is only available as part of the
[Academic Research product track](https://developer.x.com/en/solutions/academic-research/products-for-researchers).
In order to use this endpoint, you must
[apply for access](https://developer.x.com/en/portal/petition/academic/is-it-right-for-you).
Learn more about the
[application and requirements for this track](https://developer.x.com/en/solutions/academic-research/application-info).

### Connect an app to the academic project

Once you are approved to use the Academic Research product track, you will see
your Academic [Project](/resources/fundamentals/developer-apps) in the
[Developer Console](https://developer.x.com/en/portal/dashboard). From the
"Apps" section, click on "Add App" to connect your
[X App](/resources/fundamentals/developer-apps) to the Project.

[](https://res.cloudinary.com/practicaldev/image/fetch/s--gHFOyuDc--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/i/gb7aevhqyfvfjznd0pnd.png)

![This image displays an Academic Project in the Developer Console that does not have an App added to it yet](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-1.png.twimg.1920.png)

Then, you can either choose an existing App and connect it to your project (as
shown below).

![This image shows you the page that pops up when you try to add an App to your Academic Project](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-2.png.twimg.1920.png)

Or you can create a new App, give it a name and click complete, to connect a new
App to your Academic Project.

![This image shows you the page where you will enter a name for your new App, or enables you to select an existing App](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-3.png.twimg.1920.png)

This will give you your API keys and
[Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token) that you can
then use to connect to the full-archive search endpoint.

![This image shows you the page that you are shown after you create a new App that displays your keys and tokens](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-4.png.twimg.1920.png)

**Please note**

The keys in the screenshot above are hidden, but in your own Developer Console,
you will be able to see the actual values for the API Key, API Secret Key, and
Bearer Token. Save these keys and the Bearer Token because you will need those
for calling the full-archive search endpoint.

### Connecting to the full-archive search endpoint

The cURL command below shows how you can get historical Posts from @XDevelopers
handle. Replace the \$BEARER\_TOKEN with your own Bearer Token, paste the full
request in your terminal, and press "return".

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'
```

You will see the response JSON.

By default, only the 10 most recent Posts will be returned. If you want more
than 10 Posts per request, you can use the max\_results parameter and set it to
a maximum of 500 Posts per request, as shown below:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

### Building queries

As you can see in the example calls above, using the query parameter, you can
specify the data that you want to search for. As an example, if you wanted to
get all Posts that contain the word *covid* or the word *coronavirus*, you can
use the OR operator within brackets, and your query can be
`(covid OR coronavirus)` and thus your API call will look like the following:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

Similarly, if you want all Posts that contain the words *covid19* that are not
reposts, you can use the is:retweet operator with the logical NOT (represented
by -), so your query can be covid19 -is:retweet and your API call will be:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

Check out
[this guide for a complete list of operators](/x-api/posts/search/integrate/build-a-query)
that are supported in the full-archive search endpoint.

### Using the start\_time and end\_time parameters to get historical Posts

When using the full-archive search endpoint, by default Posts from the last 30
days will be returned. If you want to get Posts that are older than 30 days,
you can use the start\_time and end\_time parameters in your API call. These
parameters must be in a valid RFC3339 date-time format, for example
2020-12-21T13:00:00.00Z. Thus, if you want to get all Posts from the XDevelopers
account for the month of December 2020, your API call will be:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'
```

### Getting geo-tagged historical Posts

Geo-tagged Posts are Posts that have geographic information associated with
them such as city, state, country etc.

#### Using has:geo operator

If you want to get Posts that have geo data, you can use the has:geo operator.
For example, the following cURL request will get only those Posts from the
@XDevelopers handle that have geo data:

```
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Aubashthorization: Bearer $BEARER_TOKEN'
```

#### Using place\_country operator

Similarly, you can limit Posts that have geo data, to a specific country, using
the place\_country operator. The cURL command below will get all Posts from the
@XDevelopers handle from the United States:

```
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--hbasheader 'Authorization: Bearer XXXXX'
```

The country is specified above using the ISO alpha-2 character code. Valid ISO
codes can be found [here](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

### Getting more than 500 historical Posts using the next\_token

As mentioned above, by default you can only get up to 500 Posts per request for
a query to the full-archive search endpoint. If there are more than 500 Posts
available for your query, your json response will include a next\_token which you
can append to your API call in order to get the next available Posts for this
query. This next\_token is available in the meta object of your JSON response,
which looks something:

```
{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
```

Hence, to get the next available Posts, use the next\_token value from this meta
object and use the value as the value for the next\_token in your API call to the
full-archive search endpoint as shown below (You will use your own Bearer Token
and the value that you get for the Next Token for your previous API call).

```
curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'
```

This way, you can keep checking if a next\_token is available and if you have not
reached your desired number of Posts to be collected, you can keep calling the
full-archive endpoint with the new next\_token for each request.

Below are some resources that can help you when using the full-archive search
endpoint. We would love to hear your feedback. Reach out to us on
[@XDevelopers](https://x.com/XDevelopers) or on our
[community forums](https://devcommunity.x.com/) with questions about this
endpoint.

### Additional resources

* [Full-archive search endpoint API reference](/x-api/posts/full-archive-search)
* [Learn the basics of building a search query](/x-api/posts/search/integrate/build-a-query)