Getting started with the sampled stream endpoint

This quick start guide will help you make your first request to the sampled stream endpoint using a cURL request. cURL is a command line tool which allows you to make requests with minimal configuration.

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

Prerequisites

To complete this guide, you will need to have a set of keys and tokens to authenticate your request. You can generate these keys and tokens by following these steps:

  • Sign up for a developer account and receive approval.
  • Create a Project and an associated developer App in the developer portal.
  • Navigate to your App's “Keys and tokens” page to generate the required credentials. Make sure to save all credentials in a secure location.
 

Steps to build a sampled stream request

Step one: Start with a cURL command

In this quick start, we are going to use a simple cURL request to connect a real-time stream to Twitter that will deliver 1% of all publicly available Tweets. The sampled stream endpoint is a very simple one. All you will have to do is replace or add a couple of elements of the below request and submit it to your command line tool.

      curl -X GET "https://api.twitter.com/2/tweets/sample/stream" \
-H "Authorization: Bearer $APP_ACCESS_TOKEN" 
    

Step two: Authenticate your request

Since sampled stream requires OAuth 2.0 App-Only authentication, you will need to replace $APP_ACCESS_TOKEN with the App Access Token that you generated in the prerequisites. 
 

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

If you connect to the stream after step two, you will receive the default Tweet object fields in your response: id and text.

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

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

  1. The additional tweet.created_at field in the primary Tweet objects.
  2. The associated authors’ user object’s default fields for the returned Tweets: id, name, username
  3. The additional  user.created_at field in the associated user objects. 
     

To request these fields, you will need to pass the following in your request:
 

Key Value Returned fields
tweet.fields created_at tweets.created_at
expansions author_id includes.users.id, includes.users.name, includes.users.username
user.fields created_at includes.users.created_at


Once you've added these, the URL in your cURL request should look like the following:

      https://api.twitter.com/2/tweets/sample/stream?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, you can submit your request to Twitter using a command line tool. If done successfully, you will receive a live stream of Tweets with payloads similar to the following:

      {
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2020-02-14T19:00:55.000Z",
      "id": "1228393702244134912",
      "text": "What did the developer write in their Valentine’s card?\n  \nwhile(true) {\n    I = Love(You);  \n}"
    },
    {
      "author_id": "2244994945",
      "created_at": "2020-02-12T17:09:56.000Z",
      "id": "1227640996038684673",
      "text": "Doctors: Googling stuff online does not make you a doctor\n\nDevelopers: https://t.co/mrju5ypPkb"
    },
    {
      "author_id": "2244994945",
      "created_at": "2019-11-27T20:26:41.000Z",
      "id": "1199786642791452673",
      "text": "C#"
    }
  ],
  "includes": {
    "users": [
      {
        "created_at": "2013-12-14T04:35:55.000Z",
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

    


If you would like to close your connection, you can press Control-C in your command line tool on either Mac or Windows systems to break the connection, or you can also close the window.