GET /labs/2/tweets

GET /labs/2/tweets

Returns a variety of information about the Tweet specified by the requested ID or list of IDs.

Endpoint URL

https://api.twitter.com/labs/2/tweets

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 App-only

OAuth 1.0a is also available for this endpoint.

Rate limit

App rate limit (Application-only): 900 requests per 15-minute window shared among all users of your app

Query parameters

NameTypeDescription
ids
 Required 
stringA comma separated list of Tweet IDs. Up to 100 are allowed in a single request.
expansions
 Optional 
enum (attachments.poll_ids, attachments.media_keys, author_id, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id)Comma-separated list of fields to expand. Expansions enable requests to expand an ID into a full object in the includes response object.
media.fields
 Optional 
enum (duration_ms, height, media_key, non_public_metrics, organic_metrics, promoted_metrics, preview_image_url, public_metrics, type, url, width)Comma-separated list of fields to return in the Tweet media object. The response will contain the selected fields only if a Tweet contains media attachments.
place.fields
 Optional 
enum (contained_within, country, country_code, full_name, geo, id, name, place_type)Comma-separated list of location fields to return. The response will contain the selected fields only if location data is present in any of the response objects.
poll.fields
 Optional 
enum (duration_minutes, end_datetime, id, options, voting_status)Comma-separated list of fields to return in the Tweet poll object. The response will contain the selected fields only if a Tweet contains a poll.
tweet.fields
 Optional 
enum (attachments, author_id, context_annotations, created_at, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, source, public_metrics, text, withheld)Comma-separated list of fields to return in the Tweet object. By default, the endpoint only returns id and text.
user.fields
 Optional 
enum (created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld)Comma-separated list of additional fields to return in the user object. By default, the endpoint does not return any user field.


Example code with offical SDKs

cURL (default fields)
cURL (optional fields)
twurl (default fields)
twurl (optional fields)
      curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.twitter.com/labs/2/tweets?ids=1067094924124872705,1212092628029698048"
    
      curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.twitter.com/labs/2/tweets?ids=1067094924124872705,1212092628029698048&expansions=attachments.media_keys&media.fields=type,duration_ms"
    
      twurl -X GET "/labs/2/tweets?ids=1067094924124872705,1212092628029698048"
    
      twurl -X GET "/labs/2/tweets?ids=1067094924124872705,1212092628029698048&expansions=attachments.media_keys&media.fields=type,duration_ms"
    

Example responses

Default fields
Optional fields
      {
  "data": {
    "id": "1067094924124872705",
    "text": "Just getting started with Twitter APIs? Find out what you need in order to build an app. Watch this video! https://t.co/Hg8nkfoizN"
  }
}
    
      {
  "data": {
    "attachments": {
      "media_keys": [
        "13_1064638969197977600"
      ]
    },
    "id": "1067094924124872705",
    "text": "Just getting started with Twitter APIs? Find out what you need in order to build an app. Watch this video! https://t.co/Hg8nkfoizN"
  },
  "includes": {
    "media": [
      {
        "duration_ms": 136637,
        "media_key": "13_1064638969197977600",
        "type": "video"
      }
    ]
  }
}
    

Response fields

NameTypeDescription
idstringUnique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
created_atdate (ISO 8601)Creation time of the Tweet.

To return this field, add tweet.fields=created_at in the request's query parameter.
textstringThe content of the Tweet.

To return this field, add tweet.fields=text in the request's query parameter.
author_idstringUnique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

You can obtain the expanded object in includes.users by adding expansions=author_id in the request's query parameter.
in_reply_to_user_idstringIf this Tweet is a Reply, indicates the User ID of the parent Tweet's author. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

You can obtain the expanded object in includes.users by adding expansions=in_reply_to_user_id in the request's query parameter.
referenced_tweetsarrayA list of Tweets this Tweet refers to. For example, if the parent Tweet is a Retweet, a Retweet with comment (also known as Quoted Tweet) or a Reply, it will include the related Tweet referenced to by its parent.

To return this field, add tweet.fields=referenced_tweets in the request's query parameter.
referenced_tweets.typeenum (retweeted, quoted, replied_to)Indicates the type of relationship between this Tweet and the Tweet returned in the response: retweeted (this Tweet is a Retweet), quoted (a Retweet with comment, also known as Quoted Tweet), or replied_to (this Tweet is a reply).
referenced_tweets.idstringThe unique identifier of the referenced Tweet.

You can obtain the expanded object in includes.tweets by adding expansions=referenced_tweets.id in the request's query parameter.
referenced_tweets.id.author_idstringThe unique identifier of the author of the referenced Tweet.

You can obtain the expanded object in includes.users by adding expansions=referenced_tweets.id.author_id in the request's query parameter.
attachmentsobjectSpecifies the type of attachments (if any) present in this Tweet.

To return this field, add tweet.fields=attachments in the request's query parameter.
attachments.media_keysarrayList of unique identifiers of media attached to this Tweet. These identifiers use the same media key format as those returned by the Media Library.

You can obtain the expanded object in includes.media by adding expansions=attachments.media_keys in the request's query parameter.
attachments.poll_idsarrayList of unique identifiers of polls present in the Tweets returned. These are returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

You can obtain the expanded object in includes.polls by adding expansions=attachments.polls_ids in the request's query parameter.
geoobjectContains details about the location tagged by the user in this Tweet, if they specified one.

To return this field, add tweet.fields=geo in the request's query parameter.
geo.coordinates.typestringDescribes the type of coordinate. The only value supported at present is Point.
geo.coordinates.coordinatesarrayA pair of decimal values representing the precise location of the user (latitude, longitude). This value be null unless the user explicitly shared their precise location.
geo.place_idstringThe unique identifier of the place, if this is a point of interest tagged in the Tweet.

You can obtain the expanded object in includes.places by adding expansions=geo.place_id in the request's query parameter.
context_annotationsarrayContains context annotations for the Tweet.

To return this field, add tweet.fields=context_annotations in the request's query parameter.
context_annotations.domainobjectContains elements which identify detailed information regarding the domain classification based on Tweet text.
context_annotations.domain.idstringContains the numeric value of the domain.
context_annotations.domain.namestringDomain name based on the Tweet text.
context_annotations.domain.descriptionstringLong form description of domain classification.
context_annotations.entityobjectContains elements which identify detailed information regarding the domain classification bases on Tweet text.
context_annotations.entity.idstringUnique value which correlates to an explicitly mentioned Person, Place, Product or Organization
context_annotations.entity.namestringName or reference of entity referenced in the Tweet.
context_annotations.entity.descriptionstringAdditional information regarding referenced entity.
entitiesobjectContains details about text that has a special meaning in a Tweet.

To return this field, add tweet.fields=entities in the request's query parameter.
entities.annotationsarrayContains details about annotations relative to the text within a Tweet.
entities.annotations.startintegerThe start position (zero-based) of the text used to annotate the Tweet.
entities.annotations.endintegerThe end position (zero based) of the text used to annotate the Tweet.
entities.annotations.probabilitynumberThe confidence score for the annotation as it correlates to the Tweet text.
entities.annotations.typestringThe description of the type of entity identified when the Tweet text was interpreted.
entities.annotations.normalized_textstringThe text used to determine the annotation type.
entities.urlsarrayContains details about text recognized as a URL.
entities.urls.startintegerThe start position (zero-based) of the recognized URL within the Tweet.
entities.urls.endintegerThe end position (zero-based) of the recognized URL within the Tweet.
entities.urls.urlstringThe URL in the format tweeted by the user.
entities.urls.expanded_urlstringThe fully resolved URL.
entities.urls.display_urlstringThe URL as displayed in the Twitter client.
entities.urls.unwound_urlstringThe full destination URL.
entities.hashtagsarrayContains details about text recognized as a Hashtag.
entities.hashtags.startintegerThe start position (zero-based) of the recognized Hashtag within the Tweet.
entities.hashtags.endintegerThe end position (zero-based) of the recognized Hashtag within the Tweet.
entities.hashtags.tagstringThe text of the Hashtag.
entities.mentionsarrayContains details about text recognized as a user mention.
entities.mentions.startintegerThe start position (zero-based) of the recognized user mention within the Tweet.
entities.mentions.endintegerThe end position (zero-based) of the recognized user mention within the Tweet.
entities.mentions.usernamestringThe part of text recognized as a user mention.

You can obtain the expanded object in includes.users by adding expansions=entities.mentions.username in the request's query parameter.
entities.cashtagsarrayContains details about text recognized as a Cashtag.
entities.cashtags.startintegerThe start position (zero-based) of the recognized Cashtag within the Tweet.
entities.cashtags.endintegerThe end position (zero-based) of the recognized Cashtag within the Tweet.
entities.cashtags.tagstringThe text of the Cashtag.
withheldobjectContains withholding details for withheld content.

To return this field, add tweet.fields=withheld in the request's query parameter.
withheld.copyrightbooleanIndicates if the content is being withheld for on the basis of copyright infringement.
withheld.country_codesarrayProvides a list of countries where this content is not available.
withheld.scopeenum (tweet, user)Indicates whether the content being withheld is a Tweet or a user.
public_metricsobjectEngagement metrics for the Tweet at the time of the request.

To return this field, add tweet.fields=public_metrics in the request's query parameter.
public_metrics.retweet_countintegerNumber of times this Tweet has been Retweeted.
public_metrics.reply_countintegerNumber of Replies of this Tweet.
public_metrics.like_countintegerNumber of Likes of this Tweet.
public_metrics.quote_countintegerNumber of times this Tweet has been Retweeted with a comment (also known as Quote).
non_public_metricsobjectNon-public engagement metrics for the Tweet at the time of the request. Requires user context authentication.

To return this field, add tweet.fields=non_public_metrics in the request's query parameter.
non_public_metrics.impression_countintegerNumber of times the Tweet has been viewed.
organic_metricsobjectOrganic engagement metrics for the Tweet at the time of the request. Requires user context authentication.
organic_metrics.impression_countintegerNumber of times the Tweet has been viewed organically.
organic_metrics.retweet_countintegerNumber of times the Tweet has been Retweeted organically.
organic_metrics.reply_countintegerNumber of replies the Tweet has received organically.
organic_metrics.like_countintegerNumber of likes the Tweet has received organically.
promoted_metricsobjectEngagement metrics for the Tweet at the time of the request in a promoted context. Requires user context authentication.
promoted_metrics.impression_countintegerNumber of times the Tweet has been viewed when promoted.
promoted_metrics.retweet_countintegerNumber of times this Tweet has been Retweeted when promoted.
promoted_metrics.reply_countintegerNumber of Replies to this Tweet when promoted.
promoted_metrics.like_countintegerNumber of Likes of this Tweet when promoted.
possibly_sensitivebooleanIndicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences.

To return this field, add tweet.fields=possibly_sensitive in the request's query parameter.
langstringLanguage of the Tweet, if detected by Twitter. Returned as a BCP47 language tag.

To return this field, add tweet.fields=lang in the request's query parameter.
sourcestringThe name of the app the user Tweeted from.

To return this field, add tweet.fields=source in the request's query parameter.
includesobjectReturns the requested expansions, if available.
includes.tweetsarrayFor referenced Tweets, this is a list of objects with the same structure as the one described in this page.
includes.usersarrayFor referenced users, this is a list of objects with the same structure as the one described by GET /users.
includes.places.idstringThe unique identifier of the place, if this is a point of interest tagged in the Tweet.
includes.places.namestringThe short name of this place, for example San Francisco.
includes.places.full_namestringA longer-form detailed place name, for example San Francisco, CA.
includes.places.place_typeenum (city, unknown, country, admin, neighborhood, poi, zip_code, metro, admin0, admin1)Specified the particular type of information represented by this place information, such as a city name, or a point of interest.
includes.places.country_codestringThe ISO Alpha-2 country code this place belongs to.
includes.places.countrystringThe full-length name of the country this place belongs to.
includes.places.contained_withinarrayReturns the identifiers of known places that contain the referenced place.
includes.places.geoobjectContains place details in GeoJSON format.
includes.places.geo.typestringThe type of place described by this object. At present, this API only returns objects of type Feature.
includes.places.geo.bboxarrayThe bounding box coordinates for this place (latitude_start, longitude_start, latitude_end, longitude_end).
includes.places.geo.geometryobjectContains GeoJSON point information for this place, if available.
includes.places.geo.coordinates.typestringDescribes the type of coordinate. The only value supported at present is Point.
includes.places.geo.coordinates.coordinatesarrayA pair of decimal values representing the precise location of the user (latitude, longitude). This value be null unless the user explicitly shared their precise location.
includes.places.geo.coordinates.propertiesobjectA dictionary containing additional properties, as defined by the GeoJSON specification. Can be empty.
includes.mediaarrayFor referenced media attachments, this is a list of objects describing media content.
includes.media.media_keystringUnique identifiers for this expanded media content. This is returned using the same media key format as returned by the Media Library.
includes.media.heightintegerHeight of this content in pixels.
includes.media.non_public_metricsobjectNon-public engagement metrics for the media content at the time of the request. Requires user context authentication.
includes.media.non_public_metrics.playback_0_countintegerThe number of users who played through to less than 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts.
includes.media.non_public_metrics.playback_25_countintegerThe number of users who played through to 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts.
includes.media.non_public_metrics.playback_50_countintegerThe number of users who played through to 50% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts.
includes.media.non_public_metrics.playback_75_countintegerThe number of users who played through to 75% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts.
includes.media.non_public_metrics.playback_100_countintegerThe number of users who played through to 100% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts.
includes.media.public_metricsobjectEngagement metrics for the media content at the time of the request.
includes.media.public_metrics.view_countintegerThe count of how many times the video attached to this Tweet has been viewed. This is the number of video views aggregated across all Tweets in which the given video has been posted. That means that the metric includes the combined views from any instance where the video has been Retweeted or reposted in separate Tweets. This returns the total count of video views from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
includes.media.organic_metricsobjectOrganic engagement metrics for the media content at the time of the request. Requires user context authentication.
includes.media.organic_metrics.playback_0_countintegerThe number of users who played through to less than 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from organic contexts.
includes.media.organic_metrics.playback_25_countintegerThe number of users who played through to 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from organic contexts.
includes.media.organic_metrics.playback_50_countintegerThe number of users who played through to 50% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from organic contexts.
includes.media.organic_metrics.playback_75_countintegerThe number of users who played through to 75% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from organic contexts.
includes.media.organic_metrics.playback_100_countintegerThe number of users who played through to 100% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from organic contexts.
includes.media.organic_metrics.view_countintegerThe count of how many times the video attached to this Tweet has been viewed. This is the number of video views aggregated across all Tweets in which the given video has been posted. That means that the metric includes the combined views from any instance where the video has been Retweeted or reposted in separate Tweets. This returns the total count of video views from organic contexts.
includes.media.promoted_metricsobjectEngagement metrics for the media content at the time of the request in a promoted context. Requires user context authentication.
includes.media.promoted_metrics.playback_0_countintegerThe number of users who played through to less than 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from promoted contexts.
includes.media.promoted_metrics.playback_25_countintegerThe number of users who played through to 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from promoted contexts.
includes.media.promoted_metrics.playback_50_countintegerThe number of users who played through to 50% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from promoted contexts.
includes.media.promoted_metrics.playback_75_countintegerThe number of users who played through to 75% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from promoted contexts.
includes.media.promoted_metrics.playback_100_countintegerThe number of users who played through to 100% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from promoted contexts.
includes.media.promoted_metrics.view_countintegerThe count of how many times the video attached to this Tweet has been viewed. This is the number of video views aggregated across all Tweets in which the given video has been posted. That means that the metric includes the combined views from any instance where the video has been Retweeted or reposted in separate Tweets. This returns the total count of video views from paid contexts.
includes.media.widthintegerWidth of this content in pixels.
includes.media.preview_image_urlstringURL to the static placeholder preview of this content.
includes.media.duration_msintegerAvailable when `includes.media.type` is `video`. Duration in milliseconds of the video.
includes.media.typeenum (animated_gif, photo, video)Type of content.
includes.pollsstringFor referenced polls, this is a list of objects describing polls.
includes.polls.idstringUnique identifiers of the expanded poll. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
includes.polls.optionsarrayContains objects describing each choice in the referenced poll.
includes.polls.options.positionintegerPosition of this choice in the poll.
includes.polls.options.labelstringText of the poll choice.
includes.polls.options.votesintegerNumber of votes this poll choice received.
includes.polls.options.voting_statusenum (open, closed)Indicates if this poll is still active and can receive votes, or if the voting is now closed.
includes.polls.end_datetimenumberSpecifies the end date and time for this poll.
includes.polls.duration_minutesintegerSpecifies the total duration of this poll.
errorsobjectContains details about errors that affected any of the requested Tweets. See Status codes and error messages for more details.