GET lists/statuses

API version 1
Updated on Wed, 2013-03-27 13:56

Returns tweet timeline for members of the specified list. Historically, retweets were not available in list timeline responses but you can now use the include_rts=true parameter to additionally receive retweet objects.

Resource URL

https://api.twitter.com/1/lists/statuses.format

Parameters

Either a list_id or a slug is required. If providing a list_slug, an owner_screen_name or owner_id is also required.

list_id required

The numerical id of the list.

slug required

You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you'll also have to specify the list owner using the owner_id or owner_screen_name parameters.

owner_screen_name optional

The screen name of the user who owns the list being requested by a slug.

owner_id optional

The user ID of the user who owns the list being requested by a slug.

since_id optional

Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.

max_id optional

Returns results with an ID less than (that is, older than) or equal to the specified ID.

per_page optional

Specifies the number of results to retrieve per page.

This parameter will soon cease to be functional See Working with Timelines.

page optional

Specifies the page of results to retrieve.

include_entities optional

When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more details.

include_rts optional

When set to either true, t or 1, the list timeline will contain native retweets (if they exist) in addition to the standard stream of tweets. The output format of retweeted tweets is identical to the representation you see in home_timeline.

Example Request

GET

https://api.twitter.com/1/lists/statuses.json?slug=team&owner_screen_name=twitter&per_page=1&page=1&include_entities=true 

[
  {
    "coordinates": null,
    "created_at": "Fri Jul 01 21:41:35 +0000 2011",
    "favorited": false,
    "truncated": false,
    "id_str": "86912355828637696",
    "entities": {
      "urls": [
 
      ],
      "hashtags": [
 
      ],
      "user_mentions": [
        {
          "name": "Siddarth",
          "id_str": "132319630",
          "id": 132319630,
          "indices": [
            0,
            5
          ],
          "screen_name": "sidd"
        }
      ]
    },
    "in_reply_to_user_id_str": "132319630",
    "contributors": null,
    "text": "@sidd Damn, you've seen through my lies!",
    "id": 86912355828637696,
    "in_reply_to_status_id_str": "86912065855434752",
    "retweet_count": 0,
    "geo": null,
    "retweeted": false,
    "in_reply_to_user_id": 132319630,
    "source": "<a href=\"http://itunes.apple.com/us/app/twitter/id409789998?mt=12\" rel=\"nofollow\">Twitter for Mac</a>",
    "in_reply_to_screen_name": "sidd",
    "user": {
      "expanded_url": null,
      "profile_sidebar_border_color": "eeeeee",
      "profile_background_tile": true,
      "profile_sidebar_fill_color": "efefef",
      "name": "Brian",
      "created_at": "Thu Feb 14 06:38:16 +0000 2008",
      "location": "San Francisco, CA",
      "profile_image_url": "http://a0.twimg.com/profile_images/1390759306/n208911_31619766_8580_normal.jpg",
      "profile_link_color": "009999",
      "id_str": "13462502",
      "follow_request_sent": false,
      "is_translator": false,
      "entities": {
        "urls": [
 
        ],
        "hashtags": [
 
        ],
        "user_mentions": [
 
        ]
      },
      "favourites_count": 1012,
      "contributors_enabled": false,
      "url": null,
      "default_profile": false,
      "id": 13462502,
      "profile_image_url_https": "https://si0.twimg.com/profile_images/1390759306/n208911_31619766_8580_normal.jpg",
      "utc_offset": -28800,
      "profile_use_background_image": true,
      "listed_count": 84,
      "lang": "en",
      "followers_count": 3370,
      "profile_text_color": "333333",
      "protected": false,
      "profile_background_color": "131516",
      "verified": false,
      "time_zone": "Pacific Time (US & Canada)",
      "description": "Professional indoorsman, part-time sherpa; erstwhile historian. Does API Policy for Twitter's Trust & Safety team but views reflected here are my own.",
      "geo_enabled": true,
      "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme14/bg.gif",
      "notifications": false,
      "default_profile_image": false,
      "statuses_count": 15571,
      "display_url": null,
      "friends_count": 614,
      "profile_background_image_url": "http://a1.twimg.com/images/themes/theme14/bg.gif",
      "following": true,
      "show_all_inline_media": true,
      "screen_name": "Truebe"
    },
    "place": null,
    "in_reply_to_status_id": 86912065855434752
  }
]