GET statuses/user_timeline

Updated on Tue, 2013-06-11 08:06

This deprecated method is replaced by GET statuses/user_timeline in API v1.1

Returns the 20 most recent statuses posted by the authenticating user. It is also possible to request another user's timeline by using the screen_name or user_id parameter. The other users timeline will only be visible if they are not protected, or if the authenticating user's follow request was accepted by the protected user.

The timeline returned is the equivalent of the one seen when you view a user's profile on twitter.com.

This method can only return up to 3,200 of a user's most recent statuses. Native retweets of other statuses by the user is included in this total, regardless of whether include_rts is specified when requesting this resource.

This method will not include retweets in the XML and JSON responses unless the include_rts parameter is set. The RSS and Atom responses will always include retweets as statuses prefixed with RT, regardless of provided parameters.

See Working with Timelines for instructions on traversing timelines.

Resource URL

http://api.twitter.com/1/statuses/user_timeline.format

Parameters

Always specify either an user_id or screen_name when requesting a user timeline.

user_id optional

The ID of the user for whom to return results for. Helpful for disambiguating when a valid user ID is also a valid screen name.

Example Values: 12345

Note:: Specifies the ID of the user to befriend. 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 for. Helpful for disambiguating when a valid screen name is also a user ID.

Example Values: noradio

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.

Example Values: 12345

count optional

Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if include_rts is not supplied. It is recommended you always send include_rts=1 when using this API method.

max_id optional

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

Example Values: 54321

page optional

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

Specifies the page of results to retrieve.

Example Values: 3

trim_user optional

When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.

Example Values: true

include_rts optional

When set to either true, t or 1,the 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. Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will no longer contain a full user object.

Example Values: true

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 detail on entities.

Example Values: true

exclude_replies optional

This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies. This parameter is only supported for JSON and XML responses.

Example Values: true

contributor_details optional

This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.

Example Values: true

Extended description

The URL pattern /version/statuses/user_timeline/:screen_name_or_user_id.format is still accepted but not recommended. As a sequence of numbers is a valid screen name we recommend using the screen_name or user_id parameter instead.

Example Request

GET	`https://api.twitter.com/1/statuses/user_timeline.json?include_entities=true&include_rts=true&screen_name=twitterapi&count=2`

```
[
```
```
  {
```
```
    "coordinates": null,
```
```
    "truncated": false,
```
```
    "favorited": false,
```

    "created_at": "Mon Jun 27 19:32:19 +0000 2011",

```
    "id_str": "85430275915526144",
```
```
    "entities": {
```
```
      "urls": [
```
```
        {
```

          "expanded_url": "http://tumblr.com/xnr37hf0yz",

```
          "url": "http://t.co/cCIWIwg",
```
```
          "indices": [
```
```
            107,
```
```
            126
```
```
          ],
```

          "display_url": "tumblr.com/xnr37hf0yz"

```
        }
```
```
      ],
```
```
      "hashtags": [
```
```
 
```
```
      ],
```
```
      "user_mentions": [
```
```
 
```
```
      ]
```
```
    },
```
```
    "in_reply_to_user_id_str": null,
```

    "text": "Misleading error message - If you try to follow a user who was recently suspended, you may see an error... http://t.co/cCIWIwg",

```
    "contributors": null,
```
```
    "in_reply_to_status_id_str": null,
```
```
    "id": 85430275915526144,
```
```
    "retweet_count": 25,
```
```
    "geo": null,
```
```
    "retweeted": false,
```
```
    "in_reply_to_user_id": null,
```

    "source": "<a href=\"http://www.tumblr.com/\" rel=\"nofollow\">Tumblr</a>",

```
    "user": {
```

      "profile_sidebar_border_color": "0094C2",

```
      "profile_background_tile": false,
```

      "profile_sidebar_fill_color": "a9d9f1",

```
      "name": "Twitter API",
```
```
      "expanded_url": null,
```
```
      "location": "San Francisco, CA",
```

      "profile_image_url": "http://a0.twimg.com/profile_images/1396428969/twitterapi_normal.png",

      "created_at": "Wed May 23 06:01:13 +0000 2007",

```
      "follow_request_sent": false,
```
```
      "is_translator": false,
```
```
      "profile_link_color": "0094C2",
```
```
      "id_str": "6253282",
```
```
      "entities": {
```
```
        "urls": [
```
```
 
```
```
        ],
```
```
        "hashtags": [
```
```
 
```
```
        ],
```
```
        "user_mentions": [
```
```
 
```
```
        ]
```
```
      },
```
```
      "contributors_enabled": true,
```
```
      "favourites_count": 20,
```
```
      "default_profile": false,
```
```
      "url": "http://dev.twitter.com",
```

      "profile_image_url_https": "https://si0.twimg.com/profile_images/1396428969/twitterapi_normal.png",

```
      "id": 6253282,
```
```
      "utc_offset": -28800,
```
```
      "listed_count": 8641,
```

      "profile_use_background_image": true,

```
      "lang": "en",
```
```
      "followers_count": 561819,
```
```
      "profile_text_color": "437792",
```
```
      "protected": false,
```

      "time_zone": "Pacific Time (US & Canada)",

```
      "geo_enabled": true,
```

      "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/229557229/twitterapi-bg.png",

```
      "notifications": false,
```

      "description": "The Real Twitter API. I tweet about API changes, service issues and happily answer questions about Twitter and our API. Don't get an answer? It's on my website.",

```
      "verified": true,
```

      "profile_background_color": "e8f2f7",

```
      "default_profile_image": false,
```
```
      "friends_count": 30,
```

      "profile_background_image_url": "http://a2.twimg.com/profile_background_images/229557229/twitterapi-bg.png",

```
      "statuses_count": 2928,
```
```
      "display_url": null,
```
```
      "screen_name": "twitterapi",
```
```
      "show_all_inline_media": false,
```
```
      "following": true
```
```
    },
```
```
    "in_reply_to_screen_name": null,
```
```
    "place": null,
```
```
    "in_reply_to_status_id": null
```
```
  },
```
```
  {
```
```
    "coordinates": null,
```
```
    "truncated": false,
```
```
    "favorited": false,
```

    "created_at": "Mon Jun 27 01:21:23 +0000 2011",

```
    "id_str": "85155733884248066",
```
```
    "entities": {
```
```
      "urls": [
```
```
        {
```

          "expanded_url": "http://tumblr.com/xnr372fyk4",

```
          "url": "http://t.co/IcQut5R",
```
```
          "indices": [
```
```
            108,
```
```
            127
```
```
          ],
```

          "display_url": "tumblr.com/xnr372fyk4"

```
        }
```
```
      ],
```
```
      "hashtags": [
```
```
 
```
```
      ],
```
```
      "user_mentions": [
```
```
 
```
```
      ]
```
```
    },
```
```
    "in_reply_to_user_id_str": null,
```

    "text": "Tweet delivery delays for streaming clients - We experienced temporary delays but the issue has now been... http://t.co/IcQut5R",

```
    "contributors": null,
```
```
    "in_reply_to_status_id_str": null,
```
```
    "id": 85155733884248066,
```
```
    "retweet_count": 45,
```
```
    "geo": null,
```
```
    "retweeted": false,
```
```
    "in_reply_to_user_id": null,
```

    "source": "<a href=\"http://www.tumblr.com/\" rel=\"nofollow\">Tumblr</a>",

```
    "user": {
```

      "profile_sidebar_border_color": "0094C2",

```
      "profile_background_tile": false,
```

      "profile_sidebar_fill_color": "a9d9f1",

```
      "name": "Twitter API",
```
```
      "expanded_url": null,
```
```
      "location": "San Francisco, CA",
```

      "profile_image_url": "http://a0.twimg.com/profile_images/1396428969/twitterapi_normal.png",

      "created_at": "Wed May 23 06:01:13 +0000 2007",

```
      "is_translator": false,
```
```
      "profile_link_color": "0094C2",
```
```
      "id_str": "6253282",
```
```
      "follow_request_sent": null,
```
```
      "entities": {
```
```
        "urls": [
```
```
 
```
```
        ],
```
```
        "hashtags": [
```
```
 
```
```
        ],
```
```
        "user_mentions": [
```
```
 
```
```
        ]
```
```
      },
```
```
      "favourites_count": 20,
```
```
      "default_profile": false,
```
```
      "contributors_enabled": true,
```
```
      "url": "http://dev.twitter.com",
```
```
      "id": 6253282,
```
```
      "utc_offset": -28800,
```

      "profile_image_url_https": "https://si0.twimg.com/profile_images/1396428969/twitterapi_normal.png",

```
      "listed_count": 8641,
```

      "profile_use_background_image": true,

```
      "lang": "en",
```
```
      "followers_count": 561747,
```
```
      "profile_text_color": "437792",
```
```
      "protected": false,
```

      "time_zone": "Pacific Time (US & Canada)",

```
      "notifications": null,
```
```
      "geo_enabled": true,
```

      "description": "The Real Twitter API. I tweet about API changes, service issues and happily answer questions about Twitter and our API. Don't get an answer? It's on my website.",

```
      "verified": true,
```

      "profile_background_color": "e8f2f7",

      "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/229557229/twitterapi-bg.png",

```
      "statuses_count": 2928,
```
```
      "default_profile_image": false,
```
```
      "friends_count": 30,
```

      "profile_background_image_url": "http://a2.twimg.com/profile_background_images/229557229/twitterapi-bg.png",

```
      "display_url": null,
```
```
      "screen_name": "twitterapi",
```
```
      "following": null,
```
```
      "show_all_inline_media": false
```
```
    },
```
```
    "in_reply_to_screen_name": null,
```
```
    "place": null,
```
```
    "in_reply_to_status_id": null
```
```
  }
```
```
]
```

Deprecation notice!

Version 1 of the API is now deprecated. This document may describe an outdated version of the API. Please move to Version 1.1 of the API as soon as possible.

Resource Information

Rate Limited?	Yes
Requires Authentication?	Supported
Response Formats	json xml rss
HTTP Methods	GET
Response Object	Tweets
API Version	v1

OAuth tool

Please Sign in with your Twitter account in order to use the OAuth tool.

GET statuses/user_timeline

This deprecated method is replaced by GET statuses/user_timeline in API v1.1

Resource URL

Parameters

Extended description

Example Request

Deprecation notice!

Resource Information

OAuth tool

Related Documentation

Related Questions