List lookup by List ID

GET /2/lists/{id}
Bearer token User token O auth2 user token

Returns a List

Path parameters

  • id string Required

    The ID of the List to get

Query parameters

  • list.fields array[string]

    A comma separated list of List fields to display.

  • expansions array[string]

    A comma separated list of fields to expand.

  • user.fields array[string]

    A comma separated list of User fields to display.

Responses

  • 200

    The request was successful

    Hide response attributes Show response attributes object
    • data object

      A Twitter List is a curated group of accounts.

      Hide data attributes Show data attributes object
      • id string Required

        The unique identifier of this List.

        Format should match the following pattern: ^[0-9]{1,19}$.

      • name string Required

        The name of this List.

      • created_at string(date-time)
      • description string
      • follower_count integer
      • member_count integer
      • owner_id string

        Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

        Format should match the following pattern: ^[0-9]{1,19}$.

      • private boolean
    • includes object
      Hide includes attribute Show includes attribute object
      • users array[object]

        The Twitter User object

        At least 1 element.

        Hide users attributes Show users attributes array[object]
        • id string Required

          Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

          Format should match the following pattern: ^[0-9]{1,19}$.

        • created_at string(date-time)

          Creation time of this user.

        • name string Required

          The friendly name of this user, as shown on their profile.

        • username string Required

          The Twitter handle (screen name) of this user.

          Format should match the following pattern: ^[A-Za-z0-9_]{1,15}$.

        • protected boolean

          Indicates if this user has chosen to protect their Tweets (in other words, if this user's Tweets are private).

        • verified boolean

          Indicate if this user is a verified Twitter User.

        • withheld object

          Indicates withholding details for withheld content.

          Hide withheld attributes Show withheld attributes object
          • country_codes array[string] Required

            A two-letter ISO 3166-1 alpha-2 country code

            At least 1 element. Format of each should match the following pattern: ^[A-Z]{2}$.

          • scope string

            Indicates that the content being withheld is a user.

            Value is user.

        • profile_image_url string(uri)

          The URL to the profile image for this user.

        • location string

          The location specified in the user's profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.

        • url string

          The URL specified in the user's profile.

        • description string

          The text of this user's profile description (also known as bio), if the user provided one.

        • entities object

          A list of metadata found in the user's profile description.

          Hide entities attributes Show entities attributes object
          • url object

            Expanded details for the URL specified in the user's profile, with start and end indices.

            Hide url attribute Show url attribute object
            • urls array[object]

              Represent the portion of text recognized as a URL.

              At least 1 element.

              Hide urls attributes Show urls attributes array[object]
              • start integer Required

                Index (zero-based) at which position this entity starts. The index is inclusive.

                Minimum value is 0.

              • end integer Required

                Index (zero-based) at which position this entity ends. The index is exclusive.

                Minimum value is 0.

              • url string(uri) Required

                A validly formatted URL.

              • expanded_url string(uri)

                A validly formatted URL.

              • display_url string

                The URL as displayed in the Twitter client.

              • unwound_url string(uri)

                Fully resolved url

              • status integer

                HTTP Status Code.

                Minimum value is 100, maximum value is 599.

              • title string

                Title of the page the URL points to.

              • description string

                Description of the URL landing page.

              • images array[object]

                Represent the information for the URL image

                At least 1 element.

                Hide images attributes Show images attributes array[object]
                • url string(uri)

                  A validly formatted URL.

                • height integer

                  The height of the media in pixels

                  Minimum value is 0.

                • width integer

                  The width of the media in pixels

                  Minimum value is 0.

          • description object
            Hide description attributes Show description attributes object
            • urls array[object]

              Represent the portion of text recognized as a URL.

              At least 1 element.

              Hide urls attributes Show urls attributes array[object]
              • start integer Required

                Index (zero-based) at which position this entity starts. The index is inclusive.

                Minimum value is 0.

              • end integer Required

                Index (zero-based) at which position this entity ends. The index is exclusive.

                Minimum value is 0.

              • url string(uri) Required

                A validly formatted URL.

              • expanded_url string(uri)

                A validly formatted URL.

              • display_url string

                The URL as displayed in the Twitter client.

              • unwound_url string(uri)

                Fully resolved url

              • status integer

                HTTP Status Code.

                Minimum value is 100, maximum value is 599.

              • title string

                Title of the page the URL points to.

              • description string

                Description of the URL landing page.

              • images array[object]

                Represent the information for the URL image

                At least 1 element.

                Hide images attributes Show images attributes array[object]
                • url string(uri)

                  A validly formatted URL.

                • height integer

                  The height of the media in pixels

                  Minimum value is 0.

                • width integer

                  The width of the media in pixels

                  Minimum value is 0.

            • hashtags array[object]

              Represent the portion of text recognized as a Hashtag, and its start and end position within the text.

              At least 1 element.

              Hide hashtags attributes Show hashtags attributes array[object]
              • start integer Required

                Index (zero-based) at which position this entity starts. The index is inclusive.

                Minimum value is 0.

              • end integer Required

                Index (zero-based) at which position this entity ends. The index is exclusive.

                Minimum value is 0.

              • tag string Required

                The text of the Hashtag

            • mentions array[object]

              Represent the portion of text recognized as a User mention, and its start and end position within the text.

              At least 1 element.

              Hide mentions attributes Show mentions attributes array[object]
              • start integer Required

                Index (zero-based) at which position this entity starts. The index is inclusive.

                Minimum value is 0.

              • end integer Required

                Index (zero-based) at which position this entity ends. The index is exclusive.

                Minimum value is 0.

              • username string Required

                The Twitter handle (screen name) of this user.

                Format should match the following pattern: ^[A-Za-z0-9_]{1,15}$.

              • id string Required

                Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

                Format should match the following pattern: ^[0-9]{1,19}$.

            • cashtags array[object]

              Represent the portion of text recognized as a Cashtag, and its start and end position within the text.

              At least 1 element.

              Hide cashtags attributes Show cashtags attributes array[object]
              • start integer Required

                Index (zero-based) at which position this entity starts. The index is inclusive.

                Minimum value is 0.

              • end integer Required

                Index (zero-based) at which position this entity ends. The index is exclusive.

                Minimum value is 0.

              • tag string Required
        • pinned_tweet_id string

          Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

          Format should match the following pattern: ^[0-9]{1,19}$.

        • public_metrics object

          A list of metrics for this user

          Hide public_metrics attributes Show public_metrics attributes object
          • followers_count integer Required

            Number of users who are following this user.

          • following_count integer Required

            Number of users this user is following.

          • tweet_count integer Required

            The number of Tweets (including Retweets) posted by this user.

          • listed_count integer Required

            The number of lists that include this user.

    • errors array[object]

      An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).

      At least 1 element.

      Hide errors attributes Show errors attributes array[object]
      • type string Required
      • title string Required
      • detail string
      • status integer
  • default

    The request has failed.

    Hide response attributes Show response attributes object
    • code integer(int32) Required
    • message string Required
GET /2/lists/{id} 
curl \
 -X GET https://api.twitter.com/2/lists/1146654567674912769 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "data": {
    "id": "1146654567674912769",
    "name": "string",
    "created_at": "2023-05-04T09:42:00+00:00",
    "description": "string",
    "follower_count": 42,
    "member_count": 42,
    "owner_id": "2244994945",
    "private": true
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "created_at": "2013-12-14T04:35:55Z",
        "name": "Twitter Dev",
        "username": "TwitterDev",
        "protected": false
      }
    ]
  },
  "errors": [
    {
      "type": "string",
      "title": "string",
      "detail": "string",
      "status": 42
    }
  ]
}
Response examples (200) 
{
  "data": {
    "id": "1146654567674912769",
    "name": "string",
    "created_at": "2025-05-04T09:42:00Z",
    "description": "string",
    "follower_count": 42,
    "member_count": 42,
    "owner_id": "2244994945",
    "private": true
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev",
        "protected": false,
        "created_at": "2013-12-14T04:35:55Z"
      }
    ]
  },
  "errors": [
    {
      "type": "string",
      "title": "string",
      "detail": "string",
      "status": 42
    }
  ]
}
Response examples (default) 
{
  "code": 42,
  "message": "string"
}
Response examples (default) 
{
  "code": 42,
  "message": "string"
}