# List details

`GET https://api.twittrapi.com/lists/details`

Name, description, owner and member and subscriber counts of a list.

HTML page: https://www.twittrapi.com/docs/reference/lists-details

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `listId` | query | string | yes |  | Numeric list ID, the number in the list URL (x.com/i/lists/<listId>). |

Every read endpoint also accepts `format=simple` (or the header `X-Response-Format: simple`) for compact, flat JSON with a fixed schema. Same price.

## Response

Raw JSON of X's ListByRestId query (data.list). X may add an errors array next to complete data when it cannot decode one nested field, e.g. the default banner; the rest of the list is still there.

With `format=simple`: {data: List}.

## Errors

| Status | When |
| --- | --- |
| 400 | listId is missing or not numeric. |

Shared errors (401 missing key, 402 no balance, 429 rate limit, 5xx) are listed on https://www.twittrapi.com/docs/helpful-infos/error-handling. Calls that fail with 400, 408, 409 or a 5xx error are refunded.

## Example request

curl:

```bash
curl 'https://api.twittrapi.com/lists/details?listId=84839422' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

Python:

```python
from twittrapi import TwittrAPI

client = TwittrAPI(api_key="YOUR_API_KEY")
data = client.lists.details("84839422")
```

Node.js:

```js
import { TwittrAPI } from "twittrapi";

const client = new TwittrAPI({ apiKey: process.env.TWITTRAPI_API_KEY });
const data = await client.lists.details("84839422");
```

RapidAPI:

```bash
curl 'https://twitter-aio.p.rapidapi.com/lists/details?listId=84839422' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
  --header 'x-rapidapi-host: twitter-aio.p.rapidapi.com'
```

## Example response

Shortened: arrays keep their first items and long strings are cut.

Raw (default):

```json
{
  "data": {
    "list": {
      "created_at": 1360088061000,
      "default_banner_media": {
        "media_info": {
          "original_img_height": 375,
          "original_img_url": "https://pbs.twimg.com/media/GkIQyCGWYAA4UdW.png",
          "original_img_width": 1125,
          "salient_rect": {
            "height": 1,
            "left": 562,
            "top": 187,
            "width": 1
          }
        }
      },
      "default_banner_media_results": {},
      "description": "Accounts managed by Twitter, Inc.",
      "facepile_urls": [
        "https://pbs.twimg.com/profile_images/1000000000000000000/example_normal.jpg",
        "https://pbs.twimg.com/profile_images/1000000000000000000/example_normal.jpg",
        "https://pbs.twimg.com/profile_images/1000000000000000000/example_normal.jpg"
      ],
      "followers_context": "989 followers including @warriors",
      "following": false,
      "id": "TGlzdDo4NDgzOTQyMg==",
      "id_str": "84839422",
      "is_member": false,
      "member_count": 81,
      "members_context": "81 members",
      "mode": "Public",
      "muting": false,
      "name": "Official Twitter Accounts",
      "pinning": false,
      "subscriber_count": 989,
      "user_results": {
        "result": {
          "__typename": "User",
          "affiliates_highlighted_label": {},
          "avatar": {
            "image_url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_normal.jpg"
          },
          "core": {
            "created_at": "Tue Feb 20 14:35:54 +0000 2007",
            "name": "X",
            "screen_name": "X"
          },
          "dm_permissions": {
            "can_dm": false
          },
          "follow_request_sent": false,
          "has_graduated_access": true,
          "id": "VXNlcjo3ODMyMTQ=",
          "is_blue_verified": true,
          "legacy": {
            "default_profile": false,
            "default_profile_image": false,
            "description": "what's happening?!",
            "entities": {
              "description": {},
              "url": {
                "urls": [
                  {
                    "display_url": "x.com",
                    "expanded_url": "https://x.com",
                    "indices": [
                      0,
                      23
                    ],
                    "url": "https://t.co/Xp0xJlcROt"
                  }
                ]
              }
            },
            "fast_followers_count": 0,
            "favourites_count": 5969,
            "follow_request_sent": false,
            "followers_count": 60685971,
            "friends_count": 1,
            "has_custom_timelines": true,
            "is_translator": false,
            "listed_count": 85171,
            "media_count": 2492,
            "needs_phone_verification": false,
            "normal_followers_count": 60685971,
            "notifications": false,
            "possibly_sensitive": false,
            "profile_banner_url": "https://pbs.twimg.com/profile_banners/783214/1690175171",
            "profile_interstitial_type": "",
… (82 more lines)
```

Simple (`format=simple`):

```json
{
  "data": {
    "id": "84839422",
    "name": "Official Twitter Accounts",
    "description": "Accounts managed by Twitter, Inc.",
    "createdAt": "2013-02-05T18:14:21Z",
    "memberCount": 81,
    "followerCount": 989,
    "private": false,
    "bannerUrl": "https://pbs.twimg.com/media/GkIQyCGWYAA4UdW.png",
    "owner": {
      "id": "783214",
      "username": "X"
    }
  }
}
```