Overview
Welcome to the new Twitter API!
We believe developers play a critical role in serving the public conversation. The creativity of developers with our API makes Twitter better for people and businesses, and makes the world a better place. As we embark on the next phase of our API, our objective is to make our developer platform better for everyone.
Our API gives you the ability to learn from and analyze the conversation on Twitter. We want to give you the tools you need to further uncover, build on, and share the value of this conversation with the world.
Over the past year, we’ve partnered with developers to build the next generation of the Twitter API to better serve our diverse community of developers. Based on developer feedback we’ve re-designed the API to better serve a broader collection of needs, introduced new capabilities and provided room for developers to grow more seamlessly. This is just the beginning.
What is the new Twitter API?
In May of 2019, we announced our intent to build the next generation of the Twitter API. Since then, we have been collecting feedback and learning from the Twitter developer community. After more than a year of collaboration, we are announcing the first collection of Twitter API v2 endpoints. Longer term, as we release new versions of core endpoints and features, you should expect they will replace the standard v1.1, premium v1.1, and enterprise endpoints as you know them today. The endpoints we have released so far are:
| Resource | Endpoint group | How it can be used |
|---|---|---|
| Tweets | Tweets lookup | Returns information about a Tweet or group of Tweets. |
| Recent search | Returns Tweets over the last seven to nine days that match your query criteria. | |
| Full-archive search | Query the complete archive of public Tweets created since the first Tweet in March 2006. This endpoint is currently only available with the Academic Research product track |
|
| User Tweet timeline | Returns the Tweets composed by, or mentioning, a specified Twitter account. | |
| User mention timeline | Returns the Tweets mentioning a specified Twitter account. | |
| Filtered stream | Delivers Tweets which match your rules through a persistent HTTPS streaming connection. | |
| Sampled stream | Delivers about a 1% sample of all new public Tweets as they happen through a persistent HTTP streaming connection. | |
| Hide replies | Hides or unhides replies to Tweets that you or other authenticated users publish. | |
| Users | Users lookup | Returns the profile information for a given user with the newly added ability to specify fields to be returned. |
| Follows lookup | Retrieve an account’s followers and who they are following using their user ID. | |
| Manage follows | Follow or unfollow users using user IDs. | |
| Manage blocks | Block or unblock users using user IDs |
If you currently use the standard v1.1 endpoints, the chart below reflects the functional replacement of a subset of the v1.1 endpoints with their v2 successors along with the v2 request rate limits for each.
| Standard v1.1 endpoints | v2 endpoint | v2 limits |
|---|---|---|
| statuses/show & statuses/lookup | Tweet lookup | 900 requests/15 min per user 300 requests/15 min per app |
| search/tweets | Search Tweets - Recent search - Full-archive search |
Recent search 450 requests/15 min per user 180 requests/15 min per app Full-archive search 300 requests/15 min per app 1 request/1 sec per app |
| statuses/user_timeline & statuses/mentions_timeline | Timelines - User Tweet timeline - User mention timeline |
User Tweet timeline 900 requests/15 min per user 1500 requests/15 min per app User mentions timeline 180 requests/15 min per user 450 requests/15 min per app |
| statuses/filter | Filtered stream - Connect to stream - Add/delete rules - Retrieve rules |
Connect to stream 50 requests/15 min Add/delete rules 450 requests/15 min Retrieve rules 450 requests/15 min |
| statuses/sample | Sampled stream | 50 requests/15 min |
| Hide replies | 50 requests/15 min | |
| users/show & users/lookup | User lookup | 900 requests/15 min per user 300 requests/15 min per app |
| v1.1 followers/ids, v1.1 followers/list, v1.1 friends/ids, & v1.1 friends/list | Follows lookup | 15 requests/15 min per user 15 requests/15 min per app |
| v1.1 friendships/create, v1.1 friendships/destroy | Manage follows - Follow a user - Unfollow a user |
50 requests/15 min per user 50 requests/15 min per user |
| v1.1 blocks/create, v1.1 blocks/destroy | Manage blocks - Block a user - Unblock a user |
50 requests/15 min per user 50 requests/15 min per user |
Learn more about rate limits.
Learn about what's new and different
We’ve included some new features and functionality that will help you find more value with the Twitter API. A lot of what is new has been driven by your feedback. Some of the improvements to the API include:
- A consistent design across endpoints
- A smaller initial payload to manage and ingest
- Streamlined access to place, poll, and media objects
- Entity detection and annotations
- Access to new metrics directly within related objects
- High-confidence spam filtering
- Shortened URLs fully unwound
Before you dive in, let’s cover some of the fundamental changes we’ve made to the way you will access and consume data from the endpoints.
Discover new and updated data objects
The following five data objects are available with the v2 endpoints:
| Object | Description |
|---|---|
| Tweet | The Tweet object has a long list of root-level fields, such as id, text, and created_at. Tweet objects are also the parent object to several child objects including user, media, poll, and place. |
| User | The user object contains Twitter user account metadata describing the referenced user. |
| Media | If a Tweet contains media (such as images), then the media object can be requested using the media.fields parameter and includes fields such as the media_key, type, url, preview_image_url, and more. |
| Poll | A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object. |
| Place | The place object consists of fields such as place_id, geo object, country_code, and more. This information can be used to identify Tweets and study Tweets by location. |
Flexiblity to choose which data objects and fields you receive
When making a request to a GET endpoint, you will receive the primary data object that relates to that endpoint, which will include a set of default fields. For example, the Tweet object delivers the id and text fields as its default.
If you would like to retrieve additional fields with your request, you will have to use the fields parameter. You can also request related objects using the expansions parameter, such as a user's pinned Tweet or a media object, and then an additional fields parameter to pull any fields from this related object. Here is a full list of expansions that you can request with the different Twitter API v2 endpoints:
- author_id
- in_reply_to_user_id
- attachments.media_keys
- attachments.poll_ids
- geo.place_id
- pinned_tweet_id
- entities.mentions.username
- referenced_tweets.id.author_id
Learn more about how to use fields and expansions, and check out our full list of data objects and fields in the Twitter API v2 data dictionary.
{
"data": {
"attachments": {
"media_keys": [
"13_1260294804770041858"
]
},
"author_id": "783214",
"created_at": "2020-05-12T19:44:51.000Z",
"id": "1260294888811347969",
"public_metrics": {
"retweet_count": 5240,
"reply_count": 1844,
"like_count": 17168,
"quote_count": 3275
},
"source": "Sprinklr",
"text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y"
}
}
New metrics available within Tweets, users, and media objects
More metrics are now accessible within Tweet, user, and media objects. These metrics are both public and private, and some metrics can be broken down into an organic or promoted context for Tweet ads.
Learn more about the available metrics.
| All Tweets | Ads | ||||
|---|---|---|---|---|---|
| Object | Available metrics | Public metrics | Private metrics (requires OAuth 1.0a User Context auth) |
Organic metrics | Promoted metrics |
| tweets | retweet_count | ✔️ | ✔️ | ✔️ | |
| quote_count | ✔️ | ||||
| like_count | ✔️ | ✔️ | ✔️ | ||
| reply_count | ✔️ | ✔️ | ✔️ | ||
| impression_count | ✔️ | ✔️ | ✔️ | ||
| url_profile_clicks | ✔️ | ✔️ | ✔️ | ||
| url_link_clicks | ✔️ | ✔️ | ✔️ | ||
| user | follower_count | ✔️ | |||
| following_count | ✔️ | ||||
| tweet_count | ✔️ | ||||
| listed_count | ✔️ | ||||
| media | view_count | ✔️ | |||
| playback_0_count playback_25_count playback_50_count playback_75_count playback_100_count |
✔️ | ||||
"public_metrics": {
"retweet_count": 5239,
"reply_count": 1844,
"like_count": 17168,
"quote_count": 3275
}
"non_public_metrics": {
"impression_count": 956,
"user_profile_clicks": 34,
"url_link_clicks": 57
}
"organic_metrics": {
"impression_count": 956,
"like_count": 1244,
"reply_count": 300,
"user_profile_clicks": 150
"url_link_clicks": 57
}
"promoted_metrics": {
"impression_count": 25086,
"like_count": 9045,
"reply_count": 637,
"user_profile_clicks": 265,
"url_link_clicks": 48
}
Tweet annotations
Annotations can be used to discover Tweets on topics of interest or to segment Tweets by entity categories. Tweets are analyzed and annotated based on the content of the Tweet text by both semantic labeling and internal machine learning algorithms. These annotations are now available via API in the response payload. We call these new elements “annotations” and they are delivered as two fields, context_annotations and entity, and can be used to filter search and streaming results using operators by the same name.
Learn more about Tweet annotations.
"context_annotations": [
{
"domain": {
"id": "45",
"name": "Brand Vertical",
"description": "Top level entities that describe a Brands industry"
}
},
{
"domain": {
"id": "46",
"name": "Brand Category",
"description": "Categories within Brand Verticals that narrow down the scope of Brands"
},
"entity": {
"id": "781974596752842752",
"name": "Services"
}
},
{
"domain": {
"id": "47",
"name": "Brand",
"description": "Brands and Companies"
},
"entity": {
"id": "10026364281",
"name": "Apple"
}
},
{
"domain": {
"id": "48",
"name": "Product",
"description": "Products created by Brands. Examples: Ford Explorer, Apple iPhone."
},
"entity": {
"id": "10044903039",
"name": "Apple - iOS"
}
}
],
"created_at": "2020-05-12T19:44:51.000Z",
"entities": {
"annotations": [
{
"start": 49,
"end": 51,
"probability": 0.8997,
"type": "Product",
"normalized_text": "iOS"
}
]
Track threaded conversations
A new filter operator, conversation_id, matches Tweets that share a common conversation ID, and is available for both recent search and filtered stream. A conversation ID is the Tweet ID of the Tweet that started the conversation. When a Tweet is part of a conversation thread, the conversation ID for that Tweet will match the parent most Tweet ID.
Learn more about conversation ID.
Get Started
In order to use v2 endpoints you will need the following things to get started.
- An approved Twitter developer account
- If you already have a developer account, activate the new developer portal.
- A registered developer App created within a Project
- Keys and tokens from the registered developer App in a Project
You can add an existing App to your new Project. While you are setting up your Project you should see an option to add any of your standalone Apps.
For additional information on how to proceed once you’ve obtained an approved Twitter developer account account check out our Getting Started guide.
If you are academic researcher, then you can apply for the Academic Research product track. If you are eligible, this will give you access to an academic project that will give you access to the full-archive search endpoint, a higher monthly Tweet cap and enhanced filtering capabilities on the filtered stream and recent search endpoints. Learn more about the Academic Research product track on our academic research hub.
Authentication
With the new Twitter API, you’ll use two different authentication patterns, OAuth 1.0a User Context and OAuth 2.0 Bearer token, to access each endpoint. Each serves a different purpose when making requests to the endpoints. OAuth 2.0 Bearer token is required to make requests on behalf of your developer App, whereas OAuth 1.0a User Context authentication is required when making a request on behalf of others Twitter users.
Tools and Code
To help you get started and familiarize yourself with the new endpoints and capabilities we have a few options to jump start your work:
First, we have a Twitter Postman collection that allows you to use the Postman client to make requests of and connect to the individual endpoints. This is a low friction way to test authentication and experiment with the endpoints. It’s important to note the Postman client is best for RESTful endpoints, but you can copy requests to streaming endpoints from the tool and paste them into your command line tool.
If you want to dig deeper, we’ve also provided a list of both Twitter supported and third party libraries in Ruby, Python, Node, Java, and many more. For additional context, take a look at our tools and libraries page.
Migrating to updated endpoints
As you start to explore the new Twitter v2 endpoints, we’ve built a series of detailed migration guides to help you compare and contrast each updated endpoints' capabilities compared to older versions:
- Tweets
- Tweets lookup
- Recent search
- Full-archive search
- User Tweet timeline
- User mention timeline
- Filtered stream
- Sampled stream
- Hide replies
- Users
- Users lookup
- Follows lookup
- Manage follows
- Manage blocks
Migrating to the new data format
As you move from v1.1 or enterprise to v2.0 it is important to understand that the format the data are delivered in has changed significantly. We have added new fields, modified the sequence of fields and in some cases removed elements as well.
The following is a series of different payloads that span across different versions and tiers to help illustrate the difference.
- Standard 1.1 Search (default mode)
- Standard 1.1 Search (extended)
- v2 Recent Search
- v2 Full-archive Search
- Standard v1.1 Filtered Stream
- v2 Filtered Stream
- Standard v1.1 Statuses Show
- v2 Tweets
- v1.1 Standard user/show
- v2 Users
What’s next?
Those of you who have used the platform for some time will notice that many of the new endpoints are aligned with existing standard v1.1, premium v1.1, and enterprise endpoints. Indeed, we intend for these to replace all three versions in the future. For more details on what we’re planning, including our planned sequence of releases and migrations, take a look at our “Guide to the future of the Twitter API”
Stay up to date
The Twitter API will rapidly evolve from here. To see what we plan to do next, take a look at our roadmap. As things progress you may also track what we’ve been up to at a more granular level use our changelog.
What should we build next?
As we build out additional capabilities of the Twitter API v2 we want to continue to hear from you. We welcome and encourage feedback from you.
Take a look at the ideas that have already been submitted, show your support for those that correlate with your needs and provide feedback as well!
