Tweets and Users v2

Interested in exploring Labs?
 The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.

Still using v1?
 This page documents the current version of these endpoints, however you can still reference the previous version. You should also check out our version migration guide and review our changelog.
 

Overview

Endpoints included in the Tweets and Users preview allows you to request information about a specified Tweet or Twitter user. These endpoints are best used to get up-to-date details, to verify that a Tweet or a User is available, or to update your stored details following a compliance event.
 

Retrieve Tweet

The GET method to the Tweets resource returns information about a Tweet or group of Tweets. The response includes metadata such as the Tweet text, author, media attachments, metrics and more.

This endpoint accepts either OAuth 1.0a user context or OAuth 2.0 Bearer token authentication methods. If the requested Tweets are protected, you must use OAuth 1.0a user context and the access tokens must represent a user that is following the protected account. 

This endpoint previews our intended replacement for GET statuses/show/:id. Only the GET method is supported currently.

Retrieve metrics

Tweet and media metrics are available in the Tweets resource. Public metrics refers to metrics that are available for anyone to access on Twitter, whereas non-public metrics refer to metrics that are not available for anyone to view.

Tweet metrics include:

  • Impressions*
  • Retweets
  • Replies
  • Likes
  • Quote Tweets
  • URL link clicks*
  • User profile clicks*

Media metrics include:

  • Video view count
  • Video view quartiles*

*Denotes non-public fields

Requesting the public_metrics and non_public_metrics fields returns metrics that are a sum of organic (posted and viewed in a regular manner on Twitter) and promoted (posted and viewed as part of an Ads campaign) contexts. You can request the organic_metrics and promoted_metrics fields to view the split between these contexts. All of the metrics listed earlier except for quote Tweets can be broken down into organic_metrics and promoted_metrics. 

To retrieve Tweet metrics, specify the field parameter in the request. For example, tweet.fields=public_metrics,non_public_metrics,organic_metrics,promoted_metrics. 

To retrieve media metrics, specify the field parameter with the media expansion parameter. For example,  expansions=attachment.media_keys&media.fields=public_metrics,non_public_metrics,organic_metrics,promoted_metrics.

If requesting only public metrics for a Tweet or media object within the Tweet, use OAuth 2.0 Bearer Token authentication. If requesting non-public, promoted, or organic metrics for a Tweet or media object within the Tweet, you must use OAuth 1.0a User Context and pass access tokens related to the requested Tweet’s owner. 

Please note that all non-public metrics are only available for Tweets that have been created within the last 30 days. Public metrics (Retweets, likes, replies, quote Tweets) are available for all Tweets since 2006.

 

Retrieve User

The GET method to the Users resource returns the profile information for a given user. The response includes profile metadata such as account name, description and location.

This endpoint accepts either OAuth 1.0a user context or OAuth 2.0 Bearer token authentication methods. If the requested user is protected, you must use OAuth 1.0a user context and the access tokens must represent either that user or a user that is following the protected account. 

This endpoint previews our intended replacement for GET users/show. Only the GET method is supported currently, but the POST method will be added in the future.

 

 

Additional resources