List object


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)


The unique identifier of this List.

"id": "2244994945"

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

name (default)


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

"name": "Twitter Lists"



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



A brief description to let users know about the List.

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




Shows how many users follow this List,

"follower_count": 198




Shows how many members are part of this List.

"member_count": 60




Indicates if the List is private.

"private": false




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 ',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