Sampled stream

Getting started with the sampled stream endpoints

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

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. The examples there are based on the 1% sampled stream and are easily updated for the 10% sampled stream. See the repository README for more details. 

Note: The steps below are also based on making requests to the 1% sampled stream. If you have Enterprise access and are working with the 10% sampled stream, see the Using the 10% sampled stream section below. 

 

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 X that will deliver 1% of all publicly available Posts. 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.x.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 Post object fields in your response: id , text, and edit_history_tweet_ids

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 three different sets of fields from different objects:

  1. The additional tweet.created_at field in the primary Post objects.
  2. The associated authors’ user object’s default fields for the returned Posts: 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.x.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 X using a command line tool. If done successfully, you will receive a live stream of Posts with payloads similar to the following:

      {
    "data": {
        "author_id": "2244994945",
        "edit_history_tweet_ids": [
            "1228393702244134912"
        ],
        "created_at": "2020-02-14T19:00:55.000Z",
        "text": "What did the developer write in their Valentine’s card?\n  \nwhile(true) {\n    I = Love(You);  \n}",
        "id": "1228393702244134912"
    },
    "includes": {
        "users": [
            {
                "created_at": "2013-12-14T04:35:55.000Z",
                "name": "Developers",
                "username": "XDevelopers",
                "id": "2244994945"
            }
        ]
    }
}
    

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. 

 

Using the 10% sampled stream

If you have Enterprise access and are working with the 10% sampled stream, note the following differences: 

  • The request URL changes from api.x.com/2/tweets/sample/stream to api.x.com/2/tweets/sample10/stream.

  • The 10% sample stream is split into 2 partitions, each requiring a connection request. Use the partition request parameter to indicate which partition you are connecting to:

    • /2/tweets/sample10/stream&partition=1

    • /2/tweets/sample10/stream&partition=2