GET /2/users/:id/followed_lists

GET /2/users/:id/followed_lists

Returns all Lists a specified user follows.

Run in Postman ❯ 
Try a live request ❯ 
Build request with API Explorer ❯ 

Endpoint URL

https://api.x.com/2/users/:id/followed_lists

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 1.0a is also available for this endpoint.

OAuth 2.0 Authorization Code with PKCE

OAuth 2.0 App-only

Rate limit

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

User rate limit (User context): 15 requests per 15-minute window per each authenticated user

OAuth 2.0 scopes required by this endpoint

tweet.read

users.read

list.read

Learn more about OAuth 2.0 Authorization Code with PKCE

Path parameters

NameTypeDescription
id
 Required 		stringThe user ID whose followed Lists you would like to retrieve.


Query parameters

NameTypeDescription
expansions
 Optional 		enum (owner_id)Expansions enable you to request additional data objects that relate to the originally returned List. The ID that represents the expanded data object will be included directly in the List 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 user object. At this time, the only expansion available to endpoints that primarily return List objects is expansions=owner_id. You will find the expanded user data object living in the includes response object.
list.fields
 Optional 		enum (created_at, follower_count, member_count, private, description, owner_id)This fields parameter enables you to select which specific List fields will deliver with each returned List objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified List fields will display directly in the List data objects.
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.
user.fields
 Optional 		enum (created_at, description, entities, id, location, most_recent_tweet_id, 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. The user fields will only be returned if you have included expansions=owner_id query parameter in your request. You will find this ID and all additional user fields in the included data object.


Example code with offical SDKs

TypeScript (Default fields)
TypeScript (Optional fields)
Java (Default fields)
Java (Optional fields) 
      (async () => {
  try {
    const getUserFollowedLists = await twitterClient.lists.userFollowedLists(
      //The ID of the user for whom to return results
      2244994945
    );
    console.dir(getUserFollowedLists, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

    
      (async () => {
  try {
    const getUserFollowedLists = await twitterClient.lists.userFollowedLists(
      //The ID of the user for whom to return results
      2244994945,
      {
        //A comma separated list of fields to expand
        expansions: ["owner_id"],

        //A comma separated list of List fields to display
        "list.fields": ["follower_count"],

        //A comma separated list of User fields to display
        "user.fields": ["username"],
      }
    );
    console.dir(getUserFollowedLists, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

    
      // Set the params values

// String | The ID of the user for whom to return results
String id = "2244994945";

try {
    MultiListResponse result = apiInstance.lists().userFollowedLists(id, null, null, null, null, null);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ListsApi#userFollowedLists");
    System.err.println("Status code: " + e.getCode());
    System.err.println("Reason: " + e.getResponseBody());
    System.err.println("Response headers: " + e.getResponseHeaders());
    e.printStackTrace();
}

    
      // Set the params values
// For full list of params visit - https://github.com/twitterdev/twitter-api-java-sdk/blob/main/docs/ListsApi.md#userFollowedLists

// String | The ID of the user for whom to return results
String id = "2244994945";

// Set<String> | A comma separated list of List fields to display
Set<String> listFields = new HashSet<>(Arrays.asList("follower_count"));

// Set<String> | A comma separated list of fields to expand
Set<String> expansions = new HashSet<>(Arrays.asList("owner_id"));

// Set<String> | A comma separated list of User fields to display
Set<String> userFields = new HashSet<>(Arrays.asList("username"));

try {
    MultiListResponse result = apiInstance.lists().userFollowedLists(id, null, null, listFields, expansions, userFields);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ListsApi#userFollowedLists");
    System.err.println("Status code: " + e.getCode());
    System.err.println("Reason: " + e.getResponseBody());
    System.err.println("Response headers: " + e.getResponseHeaders());
    e.printStackTrace();
}

Example responses

Default fields
Optional fields 
      {
  "data": [
    {
      "id": "1630685563471",
      "name": "Test List"
    }
  ],
  "meta": {
    "result_count": 1
  }
}
    
      {
  "data": [
    {
      "follower_count": 123,
      "id": "1630685563471",
      "name": "Test List",
      "owner_id": "1324848235714736129"
    }
  ],
  "includes": {
    "users": [
      {
        "username": "alanbenlee",
        "id": "1324848235714736129",
        "created_at": "2009-08-28T18:30:45.000Z",
        "name": "Alan Lee"
      }
    ]
  },
  "meta": {
    "result_count": 1
  }
}

Response fields

NameTypeDescription
id
 Default 		stringUnique identifier of this List. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
name
 Default 		stringThe name of this List.
created_atdate (ISO 8601)Creation time of this List.

To return this field, add list.fields=created_at in the request's query parameter.
privatebooleanIndicates if this List has been set to private. The List (in other words, if this is publicly viewed or not).

To return this field, add list.fields=private in the request's query parameter.
follower_countintegerNumber of users who follow this List.

To return this field, add list.fields=follower_count in the request's query parameter.
member_countintegerNumber of users who are a member of this List.

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

To return this field, add list.fields=owner_id in the request's query parameter.
descriptionstringA brief description of this List, if the owner provided one.

To return this field, add list.fields=description in the request's query parameter.
includes.usersarrayWhen including the expansions=owner_id parameter, this includes the referenced List owner in the form of a user object with their default fields and any additional fields requested using the user.fields parameter.
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.