GET /2/lists/:id/tweets

Returns a list of Tweets from the specified List.



Endpoint URL

https://api.twitter.com/2/lists/:id/tweets

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

OAuth 1.0a User context

Rate limit

App rate limit: 900 requests per 15-minute window

User rate limit: 900 requests per 15-minute window

Path parameters

NameTypeDescription
id
 Required 
stringThe ID of the List whose Tweets you would like to retrieve.


Query parameters

NameTypeDescription
expansions
 Optional 
enum (author_id)Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=pinned_tweet_id. You will find the expanded Tweet data object living in the includes response object.
max_results
 Optional 
integerThe maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token
 Optional 
stringUsed to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
tweet.fields
 Optional 
enum (attachments, author_id, context_annotations, conversation_id, created_at, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld)This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object.
user.fields
 Optional 
enum (created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld)This fields parameter enables you to select which specific user fields will deliver with the users object. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects.


Example requests

      curl "https://api.twitter.com/2/lists/84839422/tweets" -H "Authorization: OAuth $OAUTH_SIGNATURE"
    
      curl "https://api.twitter.com/2/lists/84839422/tweets?expansions=author_id?user.fields=verified" -H "Authorization: OAuth $OAUTH_SIGNATURE"
    

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"
    }
  ],
  "meta": {
    "result_count": 1
  }
}
    
      {
  "data": {
    "author_id": "2244994945",
    "created_at": "2018-11-26T16:37:10.000Z",
    "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",
    "id": "1067094924124872705"
  },
  "includes": {
    "users": [
      {
        "verified": true,
        "username": "TwitterDev",
        "id": "2244994945",
        "name": "Twitter Dev"
      }
    ]
  },
  "meta": {
    "result_count": 1
  }
}
    

Response fields

NameTypeDescription
id
 Default 
stringUnique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
text
 Default 
stringThe content of the Tweet.

To return this field, add tweet.fields=text in the request's query parameter.
created_atdate (ISO 8601)Creation time of the Tweet.

To return this field, add tweet.fields=created_at 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.
conversation_idstringThe Tweet ID of the original Tweet of the conversation (which includes direct replies, replies of replies).

To return this field, add tweet.fields=conversation_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.
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.coordinatesobjectContains details about the coordinates of the location tagged by the user in this Tweet, if they specified one.

To return this field, add tweet.fields=geo.coordinates 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. All start indices are inclusive.
entities.annotations.endintegerThe end position (zero based) of the text used to annotate the Tweet. While all other end indices are exclusive, this one is inclusive.
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. All start indices are inclusive.
entities.urls.endintegerThe end position (zero-based) of the recognized URL within the Tweet. This end index is exclusive.
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. All start indices are inclusive.
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. All start indices are inclusive.
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. All start indices are inclusive.
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. This is a private metric, and requires the use of OAuth 1.0a 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. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
non_public_metrics.url_link_clicksintegerNumber of times a user clicks on a URL link or URL preview card in a Tweet. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
non_public_metrics.user_profile_clicksintegerNumber of times a user clicks the following portions of a Tweet - display name, user name, profile picture. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
organic_metricsobjectOrganic engagement metrics for the Tweet at the time of the request. Requires user context authentication.

To return this field, add tweet.fields=organic_metrics in the request's query parameter.
organic_metrics.impression_countintegerNumber of times the Tweet has been viewed organically. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
organic_metrics.url_link_clicksintegerNumber of times a user clicks on a URL link or URL preview card in a Tweet organically. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
organic_metrics.user_profile_clicksintegerNumber of times a user clicks the following portions of a Tweet organically - display name, user name, profile picture. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
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.

To return this field, add tweet.fields=promoted_metrics in the request's query parameter.
promoted_metrics.impression_countintegerNumber of times the Tweet has been viewed when that Tweet is being promoted. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
promoted_metrics.url_link_clicksintegerNumber of times a user clicks on a URL link or URL preview card in a Tweet when it is being promoted. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
promoted_metrics.user_profile_clicksintegerNumber of times a user clicks the following portions of a Tweet when it is being promoted - display name, user name, profile picture. This is a private metric, and requires the use of OAuth 1.0a User Context authentication.
promoted_metrics.retweet_countintegerNumber of times this Tweet has been Retweeted when that Tweet is being promoted.
promoted_metrics.reply_countintegerNumber of Replies to this Tweet when that Tweet is being promoted.
promoted_metrics.like_countintegerNumber of Likes of this Tweet when that Tweet is being 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.
reply_settingsstringShows who can reply to this Tweet. Fields returned are everyone, mentionedUsers, and following.

To return this field, add tweet.fields=reply_settings 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.
includesobjectIf you include an expansion parameter, the referenced objects will be returned if available.
includes.tweetsarrayWhen including the expansions=referenced_tweets.id parameter, this includes a list of referenced Retweets, Quoted Tweets, or replies in the form of Tweet objects with their default fields and any additional fields requested using the tweet.fields parameter, assuming there is a referenced Tweet present in the returned Tweet(s).
includes.usersarrayWhen including the expansions=author_id parameter, this includes a list of referenced Tweet authors in the form of user objects with their default fields and any additional fields requested using the user.fields parameter.
errorsobjectContains details about errors that affected any of the requested Tweets. See Status codes and error messages for more details.
meta
 Default 
objectThis object contains information about the number of users returned in the current request, and pagination details.
meta.result_count
 Default 
integerThe number of users returned in this request. Note that this number may be lower than what was specified in the max_results query parameter.
meta.previous_tokenstringPagination token for the previous page of results. This value is returned when there are multiple pages of results, as the current request may only return a subset of results. To go back to the previous page, passing the value from this field in the pagination_token query parameter. When this field is not returned in the response, it means you are on the first page of results.
meta.next_tokenstringPagination token for the next page of results. This value is returned when there are multiple pages of results, as the current request may only return a subset of results. To retrieve the full list, keep passing the value from this field in the pagination_token query parameter. When this field is not returned in the response, it means you've reached the last page of results, and that there are no further pages.