GET statuses/user_timeline

API version 1.1
Updated on Thu, 2013-03-07 09:38

Returns a collection of the most recent Tweets posted by the user indicated by the screen_name or user_id parameters.

User timelines belonging to protected users may only be requested when the authenticated user either "owns" the timeline or is an approved follower of the owner.

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 Tweets. Native retweets of other statuses by the user is included in this total, regardless of whether include_rts is set to false when requesting this resource.

See Working with Timelines for instructions on traversing timelines.

See Embeddable Timelines, Embeddable Tweets, and GET statuses/oembed for tools to render Tweets according to Display Requirements.

Resource URL

https://api.twitter.com/1.1/statuses/user_timeline.json

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.

Example Values: 12345

screen_name optional

The screen name of the user for whom to return results for.

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 per distinct request. 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

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

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

include_rts optional

When set to false, the timeline will strip any native retweets (though they will still count toward both the maximal length of the timeline and the slice selected by the count parameter). Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will still contain a full user object.

Example Values: false

Example Request

GET

https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=twitterapi&count=2 

  1. [
  2.   {
  3.     "coordinates": null,
  4.     "favorited": false,
  5.     "truncated": false,
  6.     "created_at": "Wed Aug 29 17:12:58 +0000 2012",
  7.     "id_str": "240859602684612608",
  8.     "entities": {
  9.       "urls": [
  10.         {
  11.           "expanded_url": "https://dev.twitter.com/blog/twitter-certified-products",
  12.           "url": "https://t.co/MjJ8xAnT",
  13.           "indices": [
  14.             52,
  15.             73
  16.           ],
  17.           "display_url": "dev.twitter.com/blog/twitter-c\u2026"
  18.         }
  19.       ],
  20.       "hashtags": [
  21.  
  22.       ],
  23.       "user_mentions": [
  24.  
  25.       ]
  26.     },
  27.     "in_reply_to_user_id_str": null,
  28.     "contributors": null,
  29.     "text": "Introducing the Twitter Certified Products Program: https://t.co/MjJ8xAnT",
  30.     "retweet_count": 121,
  31.     "in_reply_to_status_id_str": null,
  32.     "id": 240859602684612608,
  33.     "geo": null,
  34.     "retweeted": false,
  35.     "possibly_sensitive": false,
  36.     "in_reply_to_user_id": null,
  37.     "place": null,
  38.     "user": {
  39.       "profile_sidebar_fill_color": "DDEEF6",
  40.       "profile_sidebar_border_color": "C0DEED",
  41.       "profile_background_tile": false,
  42.       "name": "Twitter API",
  43.       "profile_image_url": "http://a0.twimg.com/profile_images/2284174872/7df3h38zabcvjylnyfe3_normal.png",
  44.       "created_at": "Wed May 23 06:01:13 +0000 2007",
  45.       "location": "San Francisco, CA",
  46.       "follow_request_sent": false,
  47.       "profile_link_color": "0084B4",
  48.       "is_translator": false,
  49.       "id_str": "6253282",
  50.       "entities": {
  51.         "url": {
  52.           "urls": [
  53.             {
  54.               "expanded_url": null,
  55.               "url": "http://dev.twitter.com",
  56.               "indices": [
  57.                 0,
  58.                 22
  59.               ]
  60.             }
  61.           ]
  62.         },
  63.         "description": {
  64.           "urls": [
  65.  
  66.           ]
  67.         }
  68.       },
  69.       "default_profile": true,
  70.       "contributors_enabled": true,
  71.       "favourites_count": 24,
  72.       "url": "http://dev.twitter.com",
  73.       "profile_image_url_https": "https://si0.twimg.com/profile_images/2284174872/7df3h38zabcvjylnyfe3_normal.png",
  74.       "utc_offset": -28800,
  75.       "id": 6253282,
  76.       "profile_use_background_image": true,
  77.       "listed_count": 10775,
  78.       "profile_text_color": "333333",
  79.       "lang": "en",
  80.       "followers_count": 1212864,
  81.       "protected": false,
  82.       "notifications": null,
  83.       "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme1/bg.png",
  84.       "profile_background_color": "C0DEED",
  85.       "verified": true,
  86.       "geo_enabled": true,
  87.       "time_zone": "Pacific Time (US & Canada)",
  88.       "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.",
  89.       "default_profile_image": false,
  90.       "profile_background_image_url": "http://a0.twimg.com/images/themes/theme1/bg.png",
  91.       "statuses_count": 3333,
  92.       "friends_count": 31,
  93.       "following": null,
  94.       "show_all_inline_media": false,
  95.       "screen_name": "twitterapi"
  96.     },
  97.     "in_reply_to_screen_name": null,
  98.     "source": "<a href=\"http://sites.google.com/site/yorufukurou/\" rel=\"nofollow\">YoruFukurou</a>",
  99.     "in_reply_to_status_id": null
  100.   },
  101.   {
  102.     "coordinates": null,
  103.     "favorited": false,
  104.     "truncated": false,
  105.     "created_at": "Sat Aug 25 17:26:51 +0000 2012",
  106.     "id_str": "239413543487819778",
  107.     "entities": {
  108.       "urls": [
  109.         {
  110.           "expanded_url": "https://dev.twitter.com/issues/485",
  111.           "url": "https://t.co/p5bOzH0k",
  112.           "indices": [
  113.             97,
  114.             118
  115.           ],
  116.           "display_url": "dev.twitter.com/issues/485"
  117.         }
  118.       ],
  119.       "hashtags": [
  120.  
  121.       ],
  122.       "user_mentions": [
  123.  
  124.       ]
  125.     },
  126.     "in_reply_to_user_id_str": null,
  127.     "contributors": null,
  128.     "text": "We are working to resolve issues with application management &amp; logging in to the dev portal: https://t.co/p5bOzH0k ^TS",
  129.     "retweet_count": 105,
  130.     "in_reply_to_status_id_str": null,
  131.     "id": 239413543487819778,
  132.     "geo": null,
  133.     "retweeted": false,
  134.     "possibly_sensitive": false,
  135.     "in_reply_to_user_id": null,
  136.     "place": null,
  137.     "user": {
  138.       "profile_sidebar_fill_color": "DDEEF6",
  139.       "profile_sidebar_border_color": "C0DEED",
  140.       "profile_background_tile": false,
  141.       "name": "Twitter API",
  142.       "profile_image_url": "http://a0.twimg.com/profile_images/2284174872/7df3h38zabcvjylnyfe3_normal.png",
  143.       "created_at": "Wed May 23 06:01:13 +0000 2007",
  144.       "location": "San Francisco, CA",
  145.       "follow_request_sent": false,
  146.       "profile_link_color": "0084B4",
  147.       "is_translator": false,
  148.       "id_str": "6253282",
  149.       "entities": {
  150.         "url": {
  151.           "urls": [
  152.             {
  153.               "expanded_url": null,
  154.               "url": "http://dev.twitter.com",
  155.               "indices": [
  156.                 0,
  157.                 22
  158.               ]
  159.             }
  160.           ]
  161.         },
  162.         "description": {
  163.           "urls": [
  164.  
  165.           ]
  166.         }
  167.       },
  168.       "default_profile": true,
  169.       "contributors_enabled": true,
  170.       "favourites_count": 24,
  171.       "url": "http://dev.twitter.com",
  172.       "profile_image_url_https": "https://si0.twimg.com/profile_images/2284174872/7df3h38zabcvjylnyfe3_normal.png",
  173.       "utc_offset": -28800,
  174.       "id": 6253282,
  175.       "profile_use_background_image": true,
  176.       "listed_count": 10775,
  177.       "profile_text_color": "333333",
  178.       "lang": "en",
  179.       "followers_count": 1212864,
  180.       "protected": false,
  181.       "notifications": null,
  182.       "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme1/bg.png",
  183.       "profile_background_color": "C0DEED",
  184.       "verified": true,
  185.       "geo_enabled": true,
  186.       "time_zone": "Pacific Time (US & Canada)",
  187.       "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.",
  188.       "default_profile_image": false,
  189.       "profile_background_image_url": "http://a0.twimg.com/images/themes/theme1/bg.png",
  190.       "statuses_count": 3333,
  191.       "friends_count": 31,
  192.       "following": null,
  193.       "show_all_inline_media": false,
  194.       "screen_name": "twitterapi"
  195.     },
  196.     "in_reply_to_screen_name": null,
  197.     "source": "<a href=\"http://sites.google.com/site/yorufukurou/\" rel=\"nofollow\">YoruFukurou</a>",
  198.     "in_reply_to_status_id": null
  199.   }
  200. ]