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.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 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:
- The additional tweet.created_at field in the primary Post objects.
- The associated authors’ user object’s default fields for the returned Posts: id, name, username
- 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 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.twitter.com/2/tweets/sample/stream to api.twitter.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