List object

List

The list object contains Twitter Lists metadata describing the referenced List. The List object is the primary object returned in the List lookup endpoint. When requesting additional List fields on this endpoint, simply use the fields parameter list.fields.

At the moment, the List object cannot be found as a child object from any other data object. However, user objects can be found and expanded in the user resource. These objects are available for expansion by adding owner_id to the expansions query parameter. Use the expansion with the field parameter: list.fields when requesting additional fields to complete the primary List object and user.fields to complete the expansion object.
 

Field value Type Description How it can be used

id (default)

string

The unique identifier of this List.

"id": "2244994945"

Use this to programmatically retrieve information about a specific Twitter List.

name (default)

string

The name of the List, as defined when creating the List. 

"name": "Twitter Lists"

 

created_at

date (ISO 8601)

The UTC datetime that the List was created on Twitter.

"created_at": "2013-12-14T04:35:55.000Z"

Can be used to determine how long a List has been on Twitter

description

string

A brief description to let users know about the List.

"description": "People that are active members of the Bay area cycling community on Twitter."

 

follower_count 

integer

Shows how many users follow this List,

"follower_count": 198

 

member_count

integer

Shows how many members are part of this List.

"member_count": 60

 

private

boolean

Indicates if the List is private.

"private": false

 

owner_id

string

Unique identifier of this List's owner.

"owner_id": "1255542774432063488"

Returns the List owner ID. Can potentially be used to find out if this specifc user owns any other Lists.

Can also be used to expand user objects.

 

 

Retrieving a user object

Sample Request

In the following request, we are requesting fields for the user on the List lookup by ID endpoint. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.
 

      curl --request GET 'https://api.x.com/2/lists/1355797419175383040?list.fields=created_at,description,private,follower_count,member_count,owner_id&expansions=owner_id' --header 'Authorization: Bearer $BEARER_TOKEN'

    


Sample Response
 

      {
  "data": {
    "name": "Twitter Comms",
    "member_count": 60,
    "id": "1355797419175383040",
    "private": false,
    "description": "",
    "follower_count": 198,
    "owner_id": "257366942",
    "created_at": "2021-01-31T08:37:48.000Z"
  },
  "includes": {
    "users": [
      {
        "created_at": "2011-02-25T07:51:26.000Z",
        "name": "Ashleigh Hay 🤸🏼‍♀️",
        "id": "257366942",
        "username": "shleighhay",
        "verified": false
      }
    ]
  }
}