Getting started with the sampled stream endpoints

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

For you to be able to complete this guide, you will have need to have a set of keys and tokens, which you can generate by following these steps:

  1. Apply for a developer account and receive approval.
  2. If you already have a developer account, activate the new developer portal.
  3. Create a Project and an associated developer App in the developer portal.
  4. Navigate to your app's “Keys and tokens” page, and save your API Keys, Access Tokens, and Bearer Token to your password manager.

 

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, so we will just provide you with a request that you can copy and paste into your preferred text editor to make a slight adjustment before submitting it to a command line tool. 

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

 

Step two: Authenticate your request

Since sampled stream requires OAuth 2.0 Bearer Token authentication, you will need to replace $BEARER_TOKEN with the token that you generated and added to your password manager 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

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

  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. 

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.