GET /labs/2/tweets

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

Run in Postman ❯

Endpoint URL

https://api.x.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

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

Name	Type	Description
`ids` Required	string	A 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 -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.x.com/labs/2/tweets?ids=1067094924124872705,1212092628029698048"

      curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.x.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

      {
  "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

Name	Type	Description
`id`	string	Unique 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_at`	date (ISO 8601)	Creation time of the Tweet. To return this field, add `tweet.fields=created_at` in the request's query parameter.
`text`	string	The content of the Tweet. To return this field, add `tweet.fields=text` in the request's query parameter.
`author_id`	string	Unique 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_id`	string	If 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_tweets`	array	A 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.type`	enum (`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.id`	string	The 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_id`	string	The 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.
`attachments`	object	Specifies 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_keys`	array	List 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_ids`	array	List 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.
`geo`	object	Contains 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.type`	string	Describes the type of coordinate. The only value supported at present is `Point`.
`geo.coordinates.coordinates`	array	A 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_id`	string	The 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_annotations`	array	Contains context annotations for the Tweet. To return this field, add `tweet.fields=context_annotations` in the request's query parameter.
`context_annotations.domain`	object	Contains elements which identify detailed information regarding the domain classification based on Tweet text.
`context_annotations.domain.id`	string	Contains the numeric value of the domain.
`context_annotations.domain.name`	string	Domain name based on the Tweet text.
`context_annotations.domain.description`	string	Long form description of domain classification.
`context_annotations.entity`	object	Contains elements which identify detailed information regarding the domain classification bases on Tweet text.
`context_annotations.entity.id`	string	Unique value which correlates to an explicitly mentioned Person, Place, Product or Organization
`context_annotations.entity.name`	string	Name or reference of entity referenced in the Tweet.
`context_annotations.entity.description`	string	Additional information regarding referenced entity.
`entities`	object	Contains 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.annotations`	array	Contains details about annotations relative to the text within a Tweet.
`entities.annotations.start`	integer	The start position (zero-based) of the text used to annotate the Tweet.
`entities.annotations.end`	integer	The end position (zero based) of the text used to annotate the Tweet.
`entities.annotations.probability`	number	The confidence score for the annotation as it correlates to the Tweet text.
`entities.annotations.type`	string	The description of the type of entity identified when the Tweet text was interpreted.
`entities.annotations.normalized_text`	string	The text used to determine the annotation type.
`entities.urls`	array	Contains details about text recognized as a URL.
`entities.urls.start`	integer	The start position (zero-based) of the recognized URL within the Tweet.
`entities.urls.end`	integer	The end position (zero-based) of the recognized URL within the Tweet.
`entities.urls.url`	string	The URL in the format tweeted by the user.
`entities.urls.expanded_url`	string	The fully resolved URL.
`entities.urls.display_url`	string	The URL as displayed in the Twitter client.
`entities.urls.unwound_url`	string	The full destination URL.
`entities.hashtags`	array	Contains details about text recognized as a Hashtag.
`entities.hashtags.start`	integer	The start position (zero-based) of the recognized Hashtag within the Tweet.
`entities.hashtags.end`	integer	The end position (zero-based) of the recognized Hashtag within the Tweet.
`entities.hashtags.tag`	string	The text of the Hashtag.
`entities.mentions`	array	Contains details about text recognized as a user mention.
`entities.mentions.start`	integer	The start position (zero-based) of the recognized user mention within the Tweet.
`entities.mentions.end`	integer	The end position (zero-based) of the recognized user mention within the Tweet.
`entities.mentions.username`	string	The 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.cashtags`	array	Contains details about text recognized as a Cashtag.
`entities.cashtags.start`	integer	The start position (zero-based) of the recognized Cashtag within the Tweet.
`entities.cashtags.end`	integer	The end position (zero-based) of the recognized Cashtag within the Tweet.
`entities.cashtags.tag`	string	The text of the Cashtag.
`withheld`	object	Contains withholding details for withheld content. To return this field, add `tweet.fields=withheld` in the request's query parameter.
`withheld.copyright`	boolean	Indicates if the content is being withheld for on the basis of copyright infringement.
`withheld.country_codes`	array	Provides a list of countries where this content is not available.
`withheld.scope`	enum (`tweet`, `user`)	Indicates whether the content being withheld is a Tweet or a user.
`public_metrics`	object	Engagement 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_count`	integer	Number of times this Tweet has been Retweeted.
`public_metrics.reply_count`	integer	Number of Replies of this Tweet.
`public_metrics.like_count`	integer	Number of Likes of this Tweet.
`public_metrics.quote_count`	integer	Number of times this Tweet has been Retweeted with a comment (also known as Quote).
`non_public_metrics`	object	Non-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_count`	integer	Number of times the Tweet has been viewed.
`organic_metrics`	object	Organic engagement metrics for the Tweet at the time of the request. Requires user context authentication.
`organic_metrics.impression_count`	integer	Number of times the Tweet has been viewed organically.
`organic_metrics.retweet_count`	integer	Number of times the Tweet has been Retweeted organically.
`organic_metrics.reply_count`	integer	Number of replies the Tweet has received organically.
`organic_metrics.like_count`	integer	Number of likes the Tweet has received organically.
`promoted_metrics`	object	Engagement metrics for the Tweet at the time of the request in a promoted context. Requires user context authentication.
`promoted_metrics.impression_count`	integer	Number of times the Tweet has been viewed when promoted.
`promoted_metrics.retweet_count`	integer	Number of times this Tweet has been Retweeted when promoted.
`promoted_metrics.reply_count`	integer	Number of Replies to this Tweet when promoted.
`promoted_metrics.like_count`	integer	Number of Likes of this Tweet when promoted.
`possibly_sensitive`	boolean	Indicates 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.
`lang`	string	Language 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.
`source`	string	The name of the app the user Tweeted from. To return this field, add `tweet.fields=source` in the request's query parameter.
`includes`	object	Returns the requested expansions, if available.
`includes.tweets`	array	For referenced Tweets, this is a list of objects with the same structure as the one described in this page.
`includes.users`	array	For referenced users, this is a list of objects with the same structure as the one described by GET /users.
`includes.places.id`	string	The unique identifier of the place, if this is a point of interest tagged in the Tweet.
`includes.places.name`	string	The short name of this place, for example `San Francisco`.
`includes.places.full_name`	string	A longer-form detailed place name, for example `San Francisco, CA`.
`includes.places.place_type`	enum (`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_code`	string	The ISO Alpha-2 country code this place belongs to.
`includes.places.country`	string	The full-length name of the country this place belongs to.
`includes.places.contained_within`	array	Returns the identifiers of known places that contain the referenced place.
`includes.places.geo`	object	Contains place details in GeoJSON format.
`includes.places.geo.type`	string	The type of place described by this object. At present, this API only returns objects of type `Feature`.
`includes.places.geo.bbox`	array	The bounding box coordinates for this place (latitude_start, longitude_start, latitude_end, longitude_end).
`includes.places.geo.geometry`	object	Contains GeoJSON point information for this place, if available.
`includes.places.geo.coordinates.type`	string	Describes the type of coordinate. The only value supported at present is `Point`.
`includes.places.geo.coordinates.coordinates`	array	A 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.properties`	object	A dictionary containing additional properties, as defined by the GeoJSON specification. Can be empty.
`includes.media`	array	For referenced media attachments, this is a list of objects describing media content.
`includes.media.media_key`	string	Unique identifiers for this expanded media content. This is returned using the same media key format as returned by the Media Library.
`includes.media.height`	integer	Height of this content in pixels.
`includes.media.non_public_metrics`	object	Non-public engagement metrics for the media content at the time of the request. Requires user context authentication.
`includes.media.non_public_metrics.playback_0_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_metrics`	object	Engagement metrics for the media content at the time of the request.
`includes.media.public_metrics.view_count`	integer	The 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_metrics`	object	Organic engagement metrics for the media content at the time of the request. Requires user context authentication.
`includes.media.organic_metrics.playback_0_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_metrics`	object	Engagement 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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_count`	integer	The 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.width`	integer	Width of this content in pixels.
`includes.media.preview_image_url`	string	URL to the static placeholder preview of this content.
`includes.media.duration_ms`	integer	Available when `includes.media.type` is `video`. Duration in milliseconds of the video.
`includes.media.type`	enum (`animated_gif`, `photo`, `video`)	Type of content.
`includes.polls`	string	For referenced polls, this is a list of objects describing polls.
`includes.polls.id`	string	Unique 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.options`	array	Contains objects describing each choice in the referenced poll.
`includes.polls.options.position`	integer	Position of this choice in the poll.
`includes.polls.options.label`	string	Text of the poll choice.
`includes.polls.options.votes`	integer	Number of votes this poll choice received.
`includes.polls.options.voting_status`	enum (`open`, `closed`)	Indicates if this poll is still active and can receive votes, or if the voting is now closed.
`includes.polls.end_datetime`	number	Specifies the end date and time for this poll.
`includes.polls.duration_minutes`	integer	Specifies the total duration of this poll.
`errors`	object	Contains details about errors that affected any of the requested Tweets. See Status codes and error messages for more details.