GET statuses/mentions

Updated on Tue, 2012-07-17 10:39

Returns the 20 most recent mentions (status containing @username) for the authenticating user.

The timeline returned is the equivalent of the one seen when you view your mentions on twitter.com.

This method can only return up to 800 statuses. If include_rts is set only 800 statuses, including retweets if they exist, can be returned.

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.

See Working with Timelines for instructions on traversing timelines.

Resource URL

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

Parameters

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.

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

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 still contain a full user object. Using include_rts on this resource will only supply the first retweet of a tweet mentioning the authenticating user -- not all retweets of the authenticating user's tweets.

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

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

Example Request

GET

https://api.twitter.com/1/statuses/mentions.json?include_entities=true

  1. [
  2.   {
  3.     "coordinates": null,
  4.     "favorited": false,
  5.     "created_at": "Tue Jul 13 17:38:21 +0000 2010",
  6.     "truncated": false,
  7.     "entities": {
  8.       "urls": [
  9.         {
  10.           "expanded_url": null,
  11.           "url": "http://bit.ly/94BCpx",
  12.           "indices": [
  13.             119,
  14.             139
  15.           ]
  16.         }
  17.       ],
  18.       "hashtags": [
  19.  
  20.       ],
  21.       "user_mentions": [
  22.         {
  23.           "name": "Matt Harris",
  24.           "id": 777925,
  25.           "indices": [
  26.             56,
  27.             70
  28.           ],
  29.           "screen_name": "themattharris"
  30.         },
  31.         {
  32.           "name": "Abraham Williams",
  33.           "id": 9436992,
  34.           "indices": [
  35.             72,
  36.             80
  37.           ],
  38.           "screen_name": "abraham"
  39.         },
  40.         {
  41.           "name": "Matt Kelly",
  42.           "id": 6300552,
  43.           "indices": [
  44.             82,
  45.             93
  46.           ],
  47.           "screen_name": "mattwkelly"
  48.         }
  49.       ]
  50.     },
  51.     "text": "Just opened more slots for SF @socialappworkshop - with @themattharris, @abraham, @mattwkelly from FB- going fast tho! http://bit.ly/94BCpx",
  52.     "contributors": null,
  53.     "annotations": null,
  54.     "id": 18454047411,
  55.     "geo": null,
  56.     "in_reply_to_user_id": null,
  57.     "place": null,
  58.     "in_reply_to_screen_name": null,
  59.     "user": {
  60.       "name": "Shanley Kane",
  61.       "profile_sidebar_border_color": "BDDCAD",
  62.       "profile_background_tile": false,
  63.       "profile_sidebar_fill_color": "DDFFCC",
  64.       "created_at": "Wed Jun 24 22:24:43 +0000 2009",
  65.       "profile_image_url": "http://a0.twimg.com/profile_images/887285836/lele2_normal.jpg",
  66.       "location": "San Francisco",
  67.       "profile_link_color": "0084B4",
  68.       "follow_request_sent": false,
  69.       "url": "http://www.shanleykane.wordpress.com",
  70.       "favourites_count": 8,
  71.       "contributors_enabled": false,
  72.       "utc_offset": -28800,
  73.       "id": 50462250,
  74.       "profile_use_background_image": false,
  75.       "profile_text_color": "333333",
  76.       "protected": false,
  77.       "followers_count": 479,
  78.       "lang": "en",
  79.       "notifications": false,
  80.       "time_zone": "Pacific Time (US & Canada)",
  81.       "verified": false,
  82.       "profile_background_color": "9AE4E8",
  83.       "geo_enabled": true,
  84.       "description": "i work at apigee. this makes me an apigeek. i tweet about cloud, agile, APIs, tech stuff, pandas, propaganda, snark and trying to make it in the Valley.",
  85.       "friends_count": 440,
  86.       "statuses_count": 3100,
  87.       "profile_background_image_url": "http://s.twimg.com/a/1279228556/images/themes/theme1/bg.png",
  88.       "following": false,
  89.       "screen_name": "ShanleyKane"
  90.     },
  91.     "source": "<a href=\"http://www.tweetdeck.com\" rel=\"nofollow\">TweetDeck</a>",
  92.     "in_reply_to_status_id": null
  93.   },
  94.   {
  95.     "coordinates": null,
  96.     "favorited": false,
  97.     "created_at": "Sun Jul 11 02:45:34 +0000 2010",
  98.     "truncated": false,
  99.     "entities": {
  100.       "urls": [
  101.  
  102.       ],
  103.       "hashtags": [
  104.  
  105.       ],
  106.       "user_mentions": [
  107.         {
  108.           "name": "Matt Harris",
  109.           "id": 777925,
  110.           "indices": [
  111.             0,
  112.             14
  113.           ],
  114.           "screen_name": "themattharris"
  115.         },
  116.         {
  117.           "name": "Twitter Espa\u00f1ol",
  118.           "id": 85426644,
  119.           "indices": [
  120.             15,
  121.             26
  122.           ],
  123.           "screen_name": "twitter_es"
  124.         },
  125.         {
  126.           "name": "Paulina Goto",
  127.           "id": 110086132,
  128.           "indices": [
  129.             27,
  130.             42
  131.           ],
  132.           "screen_name": "soypaulinagoto"
  133.         }
  134.       ]
  135.     },
  136.     "text": "@themattharris @twitter_es @soypaulinagoto holaaaa!",
  137.     "contributors": null,
  138.     "annotations": null,
  139.     "id": 18240214048,
  140.     "geo": null,
  141.     "in_reply_to_user_id": 777925,
  142.     "place": null,
  143.     "in_reply_to_screen_name": "themattharris",
  144.     "user": {
  145.       "name": "leonardo daniel ",
  146.       "profile_sidebar_border_color": "87bc44",
  147.       "profile_background_tile": false,
  148.       "profile_sidebar_fill_color": "e0ff92",
  149.       "created_at": "Sun Jul 11 02:35:10 +0000 2010",
  150.       "profile_image_url": "http://s.twimg.com/a/1279228556/images/default_profile_5_normal.png",
  151.       "location": null,
  152.       "profile_link_color": "0000ff",
  153.       "follow_request_sent": false,
  154.       "url": null,
  155.       "favourites_count": 0,
  156.       "contributors_enabled": false,
  157.       "utc_offset": null,
  158.       "id": 165262200,
  159.       "profile_use_background_image": true,
  160.       "profile_text_color": "000000",
  161.       "protected": false,
  162.       "followers_count": 0,
  163.       "lang": "es",
  164.       "notifications": false,
  165.       "time_zone": null,
  166.       "verified": false,
  167.       "profile_background_color": "9ae4e8",
  168.       "geo_enabled": false,
  169.       "description": null,
  170.       "friends_count": 3,
  171.       "statuses_count": 3,
  172.       "profile_background_image_url": "http://s.twimg.com/a/1279228556/images/themes/theme1/bg.png",
  173.       "following": false,
  174.       "screen_name": "pulpin_000"
  175.     },
  176.     "source": "web",
  177.     "in_reply_to_status_id": null
  178.   },
  179.   ...
  180.   {
  181.     "coordinates": null,
  182.     "favorited": false,
  183.     "created_at": "Tue Jul 06 19:49:45 +0000 2010",
  184.     "truncated": false,
  185.     "entities": {
  186.       "urls": [
  187.         {
  188.           "expanded_url": null,
  189.           "url": "http://wiki.github.com/themattharris/annotations-hackfest/",
  190.           "indices": [
  191.             0,
  192.             58
  193.           ]
  194.         }
  195.       ],
  196.       "hashtags": [
  197.         {
  198.           "text": "devnest",
  199.           "indices": [
  200.             109,
  201.             117
  202.           ]
  203.         }
  204.       ],
  205.       "user_mentions": [
  206.         {
  207.           "name": "Matt Harris",
  208.           "id": 777925,
  209.           "indices": [
  210.             22,
  211.             36
  212.           ],
  213.           "screen_name": "themattharris"
  214.         }
  215.       ]
  216.     },
  217.     "text": "http://wiki.github.com/themattharris/annotations-hackfest/ Twitter annotations wiki page from @themattharris #devnest",
  218.     "contributors": null,
  219.     "annotations": null,
  220.     "id": 17891652167,
  221.     "geo": null,
  222.     "in_reply_to_user_id": null,
  223.     "place": null,
  224.     "in_reply_to_screen_name": null,
  225.     "user": {
  226.       "name": "Paul Kane",
  227.       "profile_sidebar_border_color": "ffffff",
  228.       "profile_background_tile": false,
  229.       "profile_sidebar_fill_color": "ffffff",
  230.       "created_at": "Thu May 03 05:58:32 +0000 2007",
  231.       "profile_image_url": "http://a3.twimg.com/profile_images/98546479/PK-front_normal.jpg",
  232.       "location": "London",
  233.       "profile_link_color": "8b8b9c",
  234.       "follow_request_sent": false,
  235.       "url": "http://pk2004.posterous.com/",
  236.       "favourites_count": 988,
  237.       "contributors_enabled": false,
  238.       "utc_offset": 0,
  239.       "id": 5732282,
  240.       "profile_use_background_image": true,
  241.       "profile_text_color": "000000",
  242.       "protected": false,
  243.       "followers_count": 1516,
  244.       "lang": "en",
  245.       "notifications": false,
  246.       "time_zone": "London",
  247.       "verified": false,
  248.       "profile_background_color": "FFFFFF",
  249.       "geo_enabled": true,
  250.       "description": "Tech geek, gadget addict, music lover, MTB'er, runner - sometimes.",
  251.       "friends_count": 1212,
  252.       "statuses_count": 3202,
  253.       "profile_background_image_url": "http://a3.twimg.com/profile_background_images/8321573/banksy.jpg",
  254.       "following": false,
  255.       "screen_name": "pk2004"
  256.     },
  257.     "source": "web",
  258.     "in_reply_to_status_id": null
  259.   }
  260. ]