Tutorials / Getting started guide

Step-by-step guide to making your first request to the new Twitter API v2

Relevant Endpoints


In this article, I will show you how you can get started quickly with the new Twitter API v2. The new API provides exciting new features such as:

  • Improvements to the response objects
  • Support for getting Twitter polls data in the API
  • Tweet annotations (that provide contextual information about a Tweet and named entities in a Tweet)
  • Support for retrieving entire conversation thread using conversation_id parameter with the search Tweets and filtered stream endpoints


Step 1: Sign up for access

In order to get started with the new Twitter API, you need a developer account. If you do not have one yet, you can sign up for one

Step 2: Create a Project and connect an App

Next, in the developer portal, create a new Project.

This image shows you the page where you will enter a name for your new project

Give it a name, select the appropriate use-case, provide a project description. Next, you can either create a new App or connect an existing App (an App is a container for your API Keys that you need in order to make an HTTP request to the Twitter API).

This image shows you the page that you are shown after you create a new App that displays your keys and tokens

Click ‘create a new App instead’ and give your App a name in order to create a new App.

this image shows the last stage of naming your app where you get your access keys, tokens, and set permissions.


Once you click complete, you will get your API Keys and the Bearer Token that you can then use to connect to the new endpoints in the Twitter API v2.

this image shows when you get your access keys, tokens.


Click the (+) next to API Key, API Secret Key and Bearer Token and copy it in a safe place on your local machine, you will need these to make the API calls in the next step.

Please note: The keys in the screenshot above are hidden, but in your own developer portal, you will be able to see the actual values for the API Key, API Secret Key and Bearer Token.

Step 3: Make an HTTP request to one of the new endpoints

Now that you have your API Keys and Bearer Token, you are ready to make your first API call to the new Twitter API v2. In this example, we will call the recent search endpoint in the new Twitter API v2. If you are familiar with the Twitter API v1.1, you may have used the search/tweets endpoint which let you search for Tweets from the last seven days. The recent search endpoint is the replacement in v2 of this search/tweets endpoint from v1.1.

We can call the recent search endpoint using one of the following approaches:

Using cURL

The first approach is to make the request in your terminal using curl. The example below shows how you can get Tweets in the last seven days from the TwitterDev account using the recent search endpoint. Just replace the $BEARER_TOKEN in the request below with your own Bearer Token (obtained from step two above), and paste the snippet in your terminal. You will get the JSON response for this request.

      curl --request GET 'https://api.twitter.com/2/tweets/search/recent?query=from:twitterdev' --header 'Authorization: Bearer $BEARER_TOKEN'


Once you are comfortable with making this API call, you can learn more advanced concepts such as modifying the query (in the request above) to get data using other keywords and operators, along with how to get additional information in your response (such as relevant user, place, polls, or Tweet objects) by exploring the documentation for the recent search endpoint and instructions on using fields and expansions to request specific data in your response.

Using sample code available on Github

Alternatively, you can use one of the code samples available on our Github to make your first request to the Twitter API v2. Currently, we have code samples available in Python, Javascript (Node), Java, Ruby. In this article, I will describe how to use the sample code for the recent search endpoint in Python.

  1. First, you will have to download the code samples from Github. Alternatively, you can also clone this repository in Github Desktop if you have it setup.
  2. Navigate to the recent_search.py. Make sure you have the requests library installed. If not, install it by running: pip install requests in your terminal.
  3. Copy your Bearer Token (obtained in step two) and set in your environment variable by running: export 'BEARER_TOKEN'='<your_bearer_token>' in your terminal.
  4. Run the recent_search.py file by running python3 recent_search.py

This will run the script and give you Tweets in the last seven days from the TwitterDev account. You can modify the query in the recent_search.py file and also specify additional fields you want returned in your JSON response.

Using Postman

Yet another way of making your first request to the new Twitter API is using Postman. Postman is a tool that lets you make HTTP requests using a graphical user interface, by easily specifying the request URL, parameters, headers etc.

To learn how to use Postman, we recommend you follow the steps that we've outlined in our recent search quick start guide.

Using select libraries

You can also use some of the libraries that support the new endpoints that are part of the new Twitter API. Check out our tools and libraries page and look for libraries in your favorite programming language. Look for the libraries that support v2 of our API.


You can use one of these approaches mentioned above to quickly make your first request to the new Twitter API v2. This will enable you to try out the new endpoints and features that are part of the new Twitter API.

If you build anything with the new Twitter API, please share it with us on this forum.

This is just the beginning. We will continue to add new endpoints to the Twitter API v2. To see what's coming, checkout our product roadmap.



Ready to build your solution?

Apply for developer access to get started