Sampled stream
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 some code snippets in different languages, please visit the sampled stream API reference page.
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:
- Apply for a developer account and receive approval.
- If you already have a developer account, activate the new developer portal.
- Create a Project and an associated developer App in the developer portal.
- 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:
- The additional tweet.created_at field in the primary Tweet objects.
- The associated authors’ user object’s default fields for the returned Tweets: 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 |
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.
