---
title: "Get Twitter List Details - API Reference"
description: "API endpoint to retrieve details of any list. Flat-rate pricing of $0.0002 per request, flexible rate limits and no overpriced subscription plans."
source: "https://docs.socialdata.tools/reference/get-list-details/"
---

GET https://api.socialdata.tools/twitter/list/{list\_id}

## Headers

**Authorization** `string` — required

Authorization Bearer header containing your SocialData API key

Example: Bearer YOUR\_API\_KEY

## Path Parameters

**list\_id** `integer` — required

The numeric ID of the desired list.

Example: 1625802236571033602

> **Caution**
> 
> When using languages where the `list_id` value exceeds the default Integer type limit (e.g., JavaScript), you should store `list_id` as a String. Use the `id_str` property returned by the API for these values

## Code Examples

#### curl

```shellscript
curl "https://api.socialdata.tools/twitter/list/1625802236571033602" \
    -H 'Authorization: Bearer API_KEY' \
    -H 'Accept: application/json'
```

#### JavaScript

```js
const listId = '1625802236571033602';
const API_KEY = 'YOUR_API_KEY_HERE';

fetch(`https://api.socialdata.tools/twitter/list/${listId}`, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```

#### Python

```python
import requests

listId = '1625802236571033602'
API_KEY = 'YOUR_API_KEY_HERE'

url = f'https://api.socialdata.tools/twitter/list/{listId}'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code}")
    print(response.text)
```

#### PHP

```php
$listId = '1625802236571033602';
$API_KEY = 'YOUR_API_KEY_HERE';

$url = "https://api.socialdata.tools/twitter/list/{$listId}";

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $API_KEY",
        "Accept: application/json"
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);

curl_close($ch);
```

## Example Responses

#### 200

```json
{
    "created_at": 1676456433000,
    "default_banner_media": {
        "media_info": {
            "original_img_url": "https:\/\/pbs.twimg.com\/media\/EXZ1_hkUYAA56JA.png",
            "original_img_width": 1125,
            "original_img_height": 375,
            "salient_rect": {
                "left": 562,
                "top": 187,
                "width": 1,
                "height": 1
            }
        }
    },
    "default_banner_media_results": {
        "result": {
            "id": "QXBpTWVkaWE6DAABCgABEXZ1\/hkUYAAKAAIQF4A+eBQgAAAA",
            "media_key": "3_1258322880099540992",
            "media_id": "1258322880099540992",
            "media_info": {
                "__typename": "ApiImage",
                "original_img_height": 375,
                "original_img_width": 1125,
                "original_img_url": "https:\/\/pbs.twimg.com\/media\/EXZ1_hkUYAA56JA.png",
                "salient_rect": {
                    "height": 1,
                    "left": 562,
                    "top": 187,
                    "width": 1
                }
            },
            "__typename": "ApiMedia"
        }
    },
    "description": "",
    "facepile_urls": [
        "https:\/\/pbs.twimg.com\/profile_images\/1685346185899294720\/jYLsROeL_mini.jpg",
        "https:\/\/pbs.twimg.com\/profile_images\/1706935000703315968\/r6aQH0jg_mini.jpg",
        "https:\/\/pbs.twimg.com\/profile_images\/1738612007451176960\/cfTlBeMZ_mini.jpg"
    ],
    "followers_context": "446 followers including @heyalexfriedman",
    "following": false,
    "id": "TGlzdDoxNjI1ODAyMjM2NTcxMDMzNjAy",
    "id_str": "1625802236571033602",
    "is_member": false,
    "member_count": 50,
    "members_context": "50 members",
    "mode": "Public",
    "muting": false,
    "name": "Soloprenuers",
    "pinning": false,
    "subscriber_count": 446,
    "user_results": {
        "result": {
            "__typename": "User",
            "id": "VXNlcjoxNDY4MTkyMzY2NDU2NTQxMTg5",
            "rest_id": "1468192366456541189",
            "affiliates_highlighted_label": [],
            "has_graduated_access": true,
            "is_blue_verified": false,
            "profile_image_shape": "Circle",
            "legacy": {
                "can_dm": true,
                "can_media_tag": true,
                "created_at": "Tue Dec 07 12:15:37 +0000 2021",
                "default_profile": true,
                "default_profile_image": false,
                "description": "I help people learn JavaScript and address any doubts they may have along the way.",
                "entities": {
                    "description": {
                        "urls": []
                    },
                    "url": {
                        "urls": [
                            {
                                "display_url": "tahajiru.com",
                                "expanded_url": "http:\/\/tahajiru.com",
                                "url": "https:\/\/t.co\/iFLD4bkkj3",
                                "indices": [
                                    0,
                                    23
                                ]
                            }
                        ]
                    }
                },
                "fast_followers_count": 0,
                "favourites_count": 5935,
                "followers_count": 103,
                "friends_count": 378,
                "has_custom_timelines": true,
                "is_translator": false,
                "listed_count": 1,
                "location": "India",
                "media_count": 103,
                "name": "Taha Jiruwala",
                "normal_followers_count": 103,
                "pinned_tweet_ids_str": [
                    "1666067236715659268"
                ],
                "possibly_sensitive": false,
                "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/1468192366456541189\/1692881657",
                "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/1469317962288943106\/aCRWoyOY_normal.jpg",
                "profile_interstitial_type": "",
                "screen_name": "tahajiru",
                "statuses_count": 3264,
                "translator_type": "none",
                "url": "https:\/\/t.co\/iFLD4bkkj3",
                "verified": false,
                "want_retweets": false,
                "withheld_in_countries": []
            }
        }
    }
}
```

#### 402

```json
{
    "status": "error",
    "message": "Insufficient balance"
}
```

#### 404

```json
{
    "status": "error",
    "message": "Not found"
}
```

#### 500

```json
{
    "status": "error",
    "message": "Failed to fetch data from Twitter"
}
```

## Response Codes

-   **200 OK** - request succeeded
-   **402 Payment Required** - not enough credits to perform this request
-   **404 Not Found** - requested list not found
-   **422 Unprocessable Content** - validation failed (e.g. one of the required parameters was not provided)
-   **500 Internal Error** - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later

## Related endpoints

-   [Get list members](https://docs.socialdata.tools/reference/get-list-members/)
-   [Get list tweets](https://docs.socialdata.tools/reference/get-list-tweets/)
-   [Get user lists](https://docs.socialdata.tools/reference/get-user-lists/)

## Before you integrate

-   [Authentication](https://docs.socialdata.tools/getting-started/authentication/)
-   [Rate limits](https://docs.socialdata.tools/getting-started/rate-limits/)
-   [Errors](https://docs.socialdata.tools/getting-started/errors/)
-   [Pricing](https://docs.socialdata.tools/getting-started/pricing/)