Create and manage lists
API Reference contents
GET lists/list
GET lists/members
GET lists/members/show
GET lists/memberships
GET lists/ownerships
GET lists/show
GET lists/statuses
GET lists/subscribers
GET lists/subscribers/show
GET lists/subscriptions
POST lists/create
POST lists/destroy
POST lists/members/create
POST lists/members/create_all
POST lists/members/destroy
POST lists/members/destroy_all
POST lists/subscribers/create
POST lists/subscribers/destroy
POST lists/update
GET lists/subscriptions
Obtain a collection of the lists the specified user is subscribed to, 20 lists per page by default. Does not include the user's own lists.
Resource URL¶
https://api.twitter.com/1.1/lists/subscriptions.json
Resource Information¶
| Response formats | JSON |
| Requires authentication? | Yes |
| Rate limited? | Yes |
| Requests / 15-min window (user auth) | 15 |
| Requests / 15-min window (app auth) | 15 |
Parameters¶
| Name | Required | Description | Default Value | Example |
| user_id | optional | The ID of the user for whom to return results. Helpful for disambiguating when a valid user ID is also a valid screen name. | ||
| screen_name | optional | The screen name of the user for whom to return results. Helpful for disambiguating when a valid screen name is also a user ID. | ||
| count | optional | The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page. | ||
| cursor | optional | Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list. It is recommended to always use cursors when the method supports them. See Cursoring for more information. |
Example Request¶
GET https://api.twitter.com/1.1/lists/subscriptions.json?cursor=-1&screen_name=episod&count=5
Example Response¶
{
"previous_cursor": 0,
"lists": [
{
"slug": "team",
"name": "team",
"uri": "/TwitterEng/team",
"created_at": "Mon Oct 03 02:48:07 +0000 2011",
"subscriber_count": 131,
"id_str": "55932616",
"member_count": 324,
"mode": "public",
"id": 55932616,
"full_name": "@TwitterEng/team",
"description": "",
"user": {
"profile_sidebar_border_color": "C6E2EE",
"profile_sidebar_fill_color": "DAECF4",
"profile_background_tile": false,
"expanded_url": null,
"name": "Twitter Engineering",
"location": "San Francisco, CA",
"created_at": "Sat Jun 16 00:14:36 +0000 2007",
"profile_image_url": "http://a2.twimg.com/profile_images/1262149685/twitter_newbird_boxed_blueonwhite_normal.png",
"is_translator": false,
"profile_link_color": "1F98C7",
"follow_request_sent": null,
"id_str": "6844292",
"entities": {
"urls": [
],
"hashtags": [
],
"user_mentions": [
]
},
"url": "http://engineering.twitter.com",
"default_profile": false,
"favourites_count": 0,
"contributors_enabled": true,
"id": 6844292,
"utc_offset": -14400,
"profile_image_url_https": "https://si0.twimg.com/profile_images/1262149685/twitter_newbird_boxed_blueonwhite_normal.png",
"profile_use_background_image": true,
"listed_count": 1493,
"profile_text_color": "663B12",
"lang": "en",
"followers_count": 132674,
"protected": false,
"profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme2/bg.gif",
"verified": true,
"geo_enabled": true,
"notifications": null,
"time_zone": "Atlantic Time (Canada)",
"description": "The official account for Twitter Engineering.",
"profile_background_color": "C6E2EE",
"profile_background_image_url": "http://a1.twimg.com/images/themes/theme2/bg.gif",
"default_profile_image": false,
"statuses_count": 61,
"friends_count": 0,
"display_url": null,
"screen_name": "TwitterEng",
"following": null,
"show_all_inline_media": true
},
"following": false
},
{
"slug": "the-brain-trust",
"name": "The Brain Trust",
"uri": "/LTRK140/the-brain-trust",
"created_at": "Sun Mar 06 20:01:50 +0000 2011",
"subscriber_count": 24,
"id_str": "37396827",
"member_count": 148,
"mode": "public",
"id": 37396827,
"full_name": "@LTRK140/the-brain-trust",
"description": "Twitter Artists, Ascii, Unicode Art.",
"user": {
"profile_sidebar_border_color": "080000",
"profile_sidebar_fill_color": "",
"profile_background_tile": true,
"name": "﹅█▄▀█▀ █▀▐━▀▄ ▌◢▌██﹅",
"location": "Toronto",
"created_at": "Fri Jun 04 16:48:39 +0000 2010",
"profile_image_url": "http://a1.twimg.com/profile_images/1315622089/Cool_Daddy_normal.png",
"is_translator": false,
"profile_link_color": "080000",
"follow_request_sent": false,
"id_str": "151938348",
"url": "http://twitter.com/KREWZO",
"favourites_count": 10,
"contributors_enabled": false,
"default_profile": false,
"id": 151938348,
"utc_offset": -28800,
"profile_image_url_https": "https://si0.twimg.com/profile_images/1315622089/Cool_Daddy_normal.png",
"profile_use_background_image": true,
"listed_count": 131,
"profile_text_color": "000000",
"lang": "en",
"followers_count": 838,
"protected": false,
"profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/285103295/ltrk140.JPG",
"verified": false,
"geo_enabled": true,
"notifications": false,
"time_zone": "Pacific Time (US & Canada)",
"description": "▓⁄─⁄⁄﹅█▄▀█▀ █▀▐━▀▄ ▌◢▌██﹅⁄─⁄⁄▓ rn •140•ASCII•UNICODE•ART• BY OZ MELO • I LIVE & WORK IN #YYZ. ★★ MOST TWEETS ARE BEST VIEWED AS A STATUS PAGE ★★ █♥█",
"profile_background_color": "030003",
"profile_background_image_url": "http://a1.twimg.com/profile_background_images/285103295/ltrk140.JPG",
"default_profile_image": false,
"statuses_count": 1006,
"friends_count": 139,
"screen_name": "LTRK140",
"following": false,
"show_all_inline_media": true
},
"following": false
},
{
"slug": "twoutside-lands",
"name": "Twoutside Lands",
"uri": "/dannyhertz/twoutside-lands",
"created_at": "Fri Aug 12 07:21:25 +0000 2011",
"subscriber_count": 12,
"id_str": "52270561",
"member_count": 25,
"mode": "public",
"id": 52270561,
"full_name": "@dannyhertz/twoutside-lands",
"description": "Tweeps @ Outside Lands 2011",
"user": {
"profile_sidebar_border_color": "4685e3",
"profile_sidebar_fill_color": "c7dced",
"profile_background_tile": false,
"expanded_url": "http://www.dannyhertz.com",
"name": "Danny Hertz",
"location": "San Francisco",
"created_at": "Sat Nov 15 02:26:09 +0000 2008",
"profile_image_url": "http://a0.twimg.com/profile_images/1546221308/6153868543_d7ab87737a_b_normal.jpeg",
"is_translator": true,
"profile_link_color": "005082",
"follow_request_sent": false,
"id_str": "17400516",
"entities": {
"urls": [
],
"hashtags": [
],
"user_mentions": [
]
},
"url": "http://t.co/90RtgWI",
"favourites_count": 243,
"contributors_enabled": false,
"default_profile": false,
"id": 17400516,
"utc_offset": -28800,
"profile_image_url_https": "https://si0.twimg.com/profile_images/1546221308/6153868543_d7ab87737a_b_normal.jpeg",
"profile_use_background_image": true,
"listed_count": 52,
"profile_text_color": "000000",
"lang": "en",
"followers_count": 2684,
"protected": false,
"profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/331345358/pamperedpuppy20091103.jpeg",
"verified": false,
"geo_enabled": true,
"notifications": false,
"time_zone": "Pacific Time (US & Canada)",
"description": "Software Engineer on the User Services team at Twitter and lead singer for the rock band Journey.",
"profile_background_color": "ffffff",
"profile_background_image_url": "http://a0.twimg.com/profile_background_images/331345358/pamperedpuppy20091103.jpeg",
"default_profile_image": false,
"statuses_count": 2318,
"friends_count": 261,
"display_url": "dannyhertz.com",
"screen_name": "dannyhertz",
"following": false,
"show_all_inline_media": true
},
"following": false
},
{
"slug": "july-6-curators",
"name": "July 6 curators",
"uri": "/townhall/july-6-curators",
"created_at": "Mon Jul 04 20:37:28 +0000 2011",
"subscriber_count": 58,
"id_str": "49286494",
"member_count": 8,
"mode": "public",
"id": 49286494,
"full_name": "@townhall/july-6-curators",
"description": "Curators helping for the Town Hall at the White House on July 6th at 2pm ET",
"user": {
"profile_sidebar_border_color": "C0DEED",
"profile_sidebar_fill_color": "DDEEF6",
"profile_background_tile": true,
"name": "Town Hall",
"location": "",
"created_at": "Tue May 31 01:50:52 +0000 2011",
"profile_image_url": "http://a2.twimg.com/profile_images/1419432899/avatar_normal.png",
"is_translator": false,
"profile_link_color": "0084B4",
"follow_request_sent": null,
"id_str": "308230587",
"url": "http://askobama.twitter.com",
"default_profile": false,
"favourites_count": 0,
"contributors_enabled": true,
"id": 308230587,
"utc_offset": -28800,
"profile_image_url_https": "https://si0.twimg.com/profile_images/1419432899/avatar_normal.png",
"profile_use_background_image": true,
"listed_count": 517,
"profile_text_color": "333333",
"lang": "en",
"followers_count": 24456,
"protected": false,
"profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/280500767/bg.jpg",
"verified": true,
"geo_enabled": false,
"notifications": null,
"time_zone": "Pacific Time (US & Canada)",
"description": "Official account for Twitter hosted town halls. Our first on July 6th, 2PM ET. ",
"profile_background_color": "C0DEED",
"profile_background_image_url": "http://a0.twimg.com/profile_background_images/280500767/bg.jpg",
"default_profile_image": false,
"statuses_count": 100,
"friends_count": 2,
"screen_name": "townhall",
"following": null,
"show_all_inline_media": true
},
"following": false
},
{
"slug": "streaming-music-industry",
"name": "Streaming Music Industry ",
"uri": "/meetmarshall/streaming-music-industry",
"created_at": "Thu Mar 31 04:04:10 +0000 2011",
"subscriber_count": 193,
"id_str": "41857276",
"member_count": 1,
"mode": "public",
"id": 41857276,
"full_name": "@meetmarshall/streaming-music-industry",
"description": "A custom list created by adding, subtracting or filtering existing lists (made using @formulists)",
"user": {
"profile_sidebar_border_color": "C0DEED",
"profile_sidebar_fill_color": "DDEEF6",
"profile_background_tile": false,
"name": "Marshall Kirkpatrick",
"location": "",
"created_at": "Mon Mar 28 20:18:47 +0000 2011",
"profile_image_url": "http://a3.twimg.com/sticky/default_profile_images/default_profile_0_normal.png",
"is_translator": false,
"profile_link_color": "0084B4",
"follow_request_sent": false,
"id_str": "273602749",
"url": "http://twitter.com/marshallk",
"default_profile": true,
"favourites_count": 0,
"contributors_enabled": false,
"id": 273602749,
"utc_offset": -28800,
"profile_image_url_https": "https://si0.twimg.com/sticky/default_profile_images/default_profile_0_normal.png",
"profile_use_background_image": true,
"listed_count": 3,
"profile_text_color": "333333",
"lang": "en",
"followers_count": 29,
"protected": false,
"profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme1/bg.png",
"verified": false,
"geo_enabled": false,
"notifications": false,
"time_zone": "Pacific Time (US & Canada)",
"description": "I just came for the lists.",
"profile_background_color": "C0DEED",
"profile_background_image_url": "http://a0.twimg.com/images/themes/theme1/bg.png",
"default_profile_image": true,
"statuses_count": 3,
"friends_count": 146,
"screen_name": "meetmarshall",
"following": false,
"show_all_inline_media": false
},
"following": false
}
],
"previous_cursor_str": "0",
"next_cursor": 1364811190668631091,
"next_cursor_str": "1364811190668631091"
}
