List Tweets lookup

​

Introduction

List Posts lookup has one available endpoint to retrieve Posts from a specified List. With this endpoint, you can build solutions that enable users to customize, organize and prioritize the Posts they see in their timeline.

There is a rate limit of 900 requests per 15 minutes for this endpoint and the response will support querying the latest 800 Posts for a given List.

You can use OAuth 1.0a User Context, [App only](https://developer.twitter.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token), or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to this endpoint. 

Account setup

To access these endpoints, you will need:

• An approved developer account.
• To authenticate using the keys and tokens from a developer App that is located within a Project. 

Learn more about getting access to the X API v2 endpoints in our getting started guide.

​

Getting started with the List Posts lookup endpoint

This quick start guide will help you make your first request to the List Posts lookup endpoint using Postman.

Please visit our X API v2 sample code GitHub repository if you want to see sample code in different languages.

​

Steps to build a List Posts lookup request

​

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we will use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “List” folder, select another folder “List Posts”, and then choose “List Posts lookup”.  

​

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do this with this endpoint, you must authenticate your request with either App only, OAuth 2.0 Authorization Code with PKCE, or OAuth 1.0a User Context authentication methods.

For simplicity’s sake, we are going to utilize App only with this request, but if you’d like to request private metrics or Posts, you will need to use one of the other authentication methods. 

To utilize App only, you must add your keys and tokens (specifically theApp only Access Token, also known as the App only Bearer Token) to Postman by selecting the environment named “X API v2” (in the top-right corner of Postman), and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

If you’ve done this correctly, these variables will automatically be pulled into the request’s authorization tab.  

​

Step three: Identify and specify which List you would like to retrieve Posts from

You must specify a List that you would like to receive within the request. You can find the List ID by navigating to x.com and clicking on a List and then looking in the URL. For example, the following URL’s List ID is 84839422.

https://twitter.com/i/lists/84839422

The target ID can be any valid List ID. In Postman, navigate to the “Params” tab, and enter your ID into the “Value” column of the id path variable. Be sure not to include any spaces before or after any ID.

​

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default Post object fields in your response: idand text.

If you would like to receive additional fields, you will have to specify those fields in your request with tweet.fields and/or expansion parameters.

For this exercise, we will request three additional sets of fields from different objects:

• The additional created_at field in the primary Lists object.

• The full user object using the expansion parameter

• The additional user.created_at field in the associated user object.

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see a similar URL next to the “Send” button:

https://api.x.com/2/lists/84839422/tweets?expansions=author_id&user.fields=created_at&max_results=1

​

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button, and you will receive a similar response to the following example response:

{
  "data": [
    {
      "author_id": "4172587277",
      "id": "1458172421115101189",
      "text": "A Alemanha registrou nesta semana um recorde de novos casos de Covid-19. Segundo o governo e especialistas em Saúde, pessoas não vacinadas são responsáveis pela situação \nhttps://t.co/4POyaPwMLu"
    }
  ],
  "includes": {
    "users": [
      {
        "username": "MomentsBrasil",
        "name": "Twitter Moments Brasil",
        "created_at": "2015-11-12T16:46:02.000Z",
        "id": "4172587277"
      }
    ]
  },
  "meta": {
    "result_count": 1,
    "next_token": "7140dibdnow9c7btw3z2vwioavpvutgzrzm9icis4ndix"
  }
}

Please note: The response of this endpoint will support querying the latest 800 Posts for a given List

​

Integration guide

This page contains information on several tools and critical concepts that you should know as you integrate the List Posts lookup endpoint into your system. We’ve broken the page into a couple of different sections:

• Helpful tools
• Key Concepts
• Authentication
• Developer portal, Projects, and Apps
• Rate limits
• Fields and expansions
• Pagination

​

Helpful tools

Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with:

​

Postman

Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our “Using Postman” page. 

​

Code samples

Are you interested in getting set up with this endpoint with some code in your preferred coding language? We’ve got a handful of different code samples available that you can use as a starting point on our Github page.

​

Third-party libraries

Take advantage of one of our communities’ third-party libraries to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag.

​

Key concepts

​

Authentication

All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, App only, or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to this endpoint. 

OAuth 1.0a User Context, which means that you must use a set of API Keys and user Access Tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the 3-legged OAuth flow.

Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a library, use a tool like Postman, or use either OAuth 2.0 or App only to authenticate your requests.

OAuth 2.0 Authorization Code with PKCE allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. 

To enable OAuth 2.0 in your App, you must enable it in your’s App’s authentication settings found in the App settings section of the developer portal.

App only just requires that you pass an App only Access Token with your request. You can either generate an App only Access Token directly within a developer App, or generate one using the POST oauth2/token endpoint.

​

Developer portal, Projects, and developer Apps

To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must sign up for a developer account, set up a Project within that account, and created a developer App within that Project. You can then find your keys and tokens within your developer App.  

​

Rate limits

Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, rate limits are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. 

This endpoint is rate limited at both the App-level and the user-level. The app rate limit means that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by using either the API Key and API Secret Key, or the Bearer Token). The user rate limit means that the authenticated user that you are making the request on behalf of can only perform a List Post lookup a certain number of times across any developer App.

The chart below shows the rate limits for each endpoint.

Fields and expansions

The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. The expansions parameter allows you to expand objects referenced in the payload. For example, looking up List Posts allows you to pull the following expansions:

• author_id

The fields parameter allows you to select exactly which fields within the different data objects you would like to receive. This endpoint delivers Post objects primarily. By default, the Post object returns the id, and text fields. To receive additional fields such as tweet.created_at or tweet.lang, you will have to specifically request those using a fields parameter. 

We’ve added a guide on using fields and expansions together to our X API v2 data dictionary.

 The chart below shows the field and expansions available for the lookup endpoint:

Pagination

Looking up List Posts can return a lot of data. To ensure we are returning consistent, high-performing results at any given time, we use pagination. Pagination is a feature in X API v2 endpoints that return more results than can be returned in a single response. When that happens, the data is returned in a series of ‘pages’. Learn more about how to paginate through results.

​

Comparing X API’s List Posts lookup endpoints

The v2 List Posts lookup endpoint will replace the standard v1.1 GET lists/statuses. If you have code, apps, or tools that use this version of the endpoint, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you.

The following tables compare the standard v1.1 and X API v2 List endpoints:

List Lookup by ID

To access the X API v2 endpoints, you must sign up for a developer account. When authenticating, you must use keys and tokens from a developer App that is located within a Project. 

Learn more about getting access to the X API v2 endpoints in our getting started page.

​

List Posts lookup: Standard v1.1 compared to X API v2

If you have been working with the standard v1.1 GET lists/statuses endpoint, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 endpoints.

• Similarities
  • Authentication methods
  • Rate limits
• Differences
  • Endpoint URLs
  • App and Project requirements
  • Data objects per request limits
  • Response data formats
  • Request parameters

​

Similarities

Authentication

Both endpoint versions support both OAuth 1.0a User Context and App only. Therefore, if you were previously using one of the standard v1.1 List Posts lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.

Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see this App only guide.

Rate limits

​

Differences

Endpoint URLs

• Standard v1.1 endpoints:
  • GET https://api.x.com/1.1/lists/statuses.json (Lookup Tweets from a specified List)
• X API v2 endpoint:
  • GET https://api.x.com/2/lists/:id/tweets (Lookup Tweets from a specified List)

App and Project requirements

The X API v2 endpoints require that you use credentials from a developer App that is associated with a Project when authenticating your requests. All X API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a project.

Data objects per request limits

The standard v1.1 /lists/statuses endpoint allows you to return up to 5000 Posts per request. The new v2 endpoints allow you to return up to 100 Posts per request. By default, 100 user objects will be returned, to change the number of results you will need to pass a query parameter max_results= with a number between 1-100; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request.

Response data format

One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload.

For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which additional fields or sets of fields should return in the payload.

The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you will need to use the fields and expansions parameters. Any Post fields that you request from this endpoint will return in the primary Post object. Any expanded object fields will return an includes object within your response. You can then match any expanded objects back to the primary Post object by matching the IDs from the primary object and in expanded objects. 

Here are examples of possible Post fields and expansions:

• attachments

• author_id

• context_annotations

• created_at

• geo

• lang

We encourage you to read more about these new parameters in their respective guides, or by reading our guide on how to use fields and expansions. 

We have also put together a data format migration guide that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. 

In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and user objects.

• At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. 

• Instead of referring to Retweeted and Quoted “statuses”, X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. 

• Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.

• X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values.  

Request parameters

The following standard v1.1 request parameters have equivalents in X API v2:

​

API reference index

For the complete API reference, click on the endpoint link below.

​

GET /2/lists/:id/tweets

Returns a list of Tweets from the specified List.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

(async () => {
  try {
    const getListTweets = await twitterClient.tweets.listsIdTweets(
      //The ID of the List to list Tweets of
      84839422
    );
    console.dir(getListTweets, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

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
  }
}

​

Response fields