GET /2/users/:id/pinned_lists

Returns the Lists pinned by a specified user.



Endpoint URL

https://api.twitter.com/2/users/:id/pinned_lists

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 1.0a User context

Rate limit

User rate limit: 15 requests per 15-minute window

Path parameters

NameTypeDescription
id
 Required 
stringThe user ID whose pinned Lists you would like to retrieve. The user’s ID must correspond to the user ID of the authenticating user, meaning that you must pass the Access Tokens associated with the user ID when authenticating your request.


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.
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. 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 requests

      curl "https://api.twitter.com/2/users/2244994945/pinned_lists" -H "Authorization: OAuth $OAUTH_SIGNATURE"
    
      curl "https://api.twitter.com/2/users/2244994945/pinned_lists?expansions=owner_id&list.fields=follower_count&user.fields=created_at" -H "Authorization: OAuth $OAUTH_SIGNATURE"
    

Example responses

      {
  "data": [
    {
      "id": "1451305624956858369",
      "name": "Test List"
    }
  ],
  "meta": {
    "result_count": 1
  }
}
    
      {
  "data": [
    {
      "follower_count": 0,
      "id": "1451305624956858369",
      "name": "Test List",
      "owner_id": "2244994945"
    }
  ],
  "includes": {
    "users": [
      {
        "username": "TwitterDev",
        "id": "2244994945",
        "created_at": "2013-12-14T04:35:55.000Z",
        "name": "Twitter Dev"
      }
    ]
  },
  "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.