We've updated the retweet payload to look a lot more like a regular tweet's payload. We find this change makes the retweet API conceptually simpler, easier and more convenient to work with and better overall. I've linked to examples of the new payload below, and will be updating documentation shortly, but first I'd like to share some background on what we've learned working on the retweet API over the past few weeks.
One of the big objectives of the retweet feature is discovering new users to follow. We wanted the original status and its author highlighted front and center so they get due credit for the tweet someone you follow found worthy of retweeting. To that end the API was designed to emphasize the original tweet by having it be the top level object. Embedded within it we provided details about who retweeted it and when. Though this makes a statement to how we'd like the feature to be thought about, logistically it doesn't degrade gracefully for clients who don't implement any retweet logic in their code. Tweets appear in timelines from people who you do not follow and unless clients differentiate those tweets visually letting you know that someone you follow has shared this tweet, confusion ensues. To mitigate this, we opted to not include retweets into the existing friends timeline. Instead we created a new parallel home timeline that would be just like the friends timeline but included retweets. That way developers could opt in to the retweet feature at their leisure. Even with this opt in policy, though, there is still a critical responsibility imposed on developers to clearly communicate to their users that a given tweet in their timeline is a retweet and who the retweet is from. The likelihood that confusion would result turned out to be too high. Additionally, with the original status as the top level object in the payload, that means consumers of the API would receive what appears to be the same tweet multiple times. In a lot of cases that's fine, in others it's problematic. After experimenting with this approach we've decided that it's a better bet to craft a payload that will degrade far more gracefully. So we've redesigned the retweet payload. Rather than having the original tweet as the top level status with embedded details about who retweeted it, the retweet is the top level object and within it we include the original tweet and its author. You'll have full access to the entire retweeted status and user as well as the original tweet and its user. So you don't have to make any additional API calls and should have everything you need to display a retweet distinctively with attribute to both the original author and the retweeter. In other words, these retweeted statuses look a whole lot like regular statuses. This new design was our instinct to begin with and we probably should have gone with it. We think it's better and hope you do too. All the same documented resources will exist. Only the payloads change. The following timeline should contain examples of the updated retweet payload. You can use this to test consuming retweets. curl http://twitter.com/statuses/user_timeline/testiverse.xml curl http://twitter.com/statuses/user_timeline/testiverse.json In the event that new tweets go into the above timeline that push the retweets out, you can access a few directly at the following urls: curl http://twitter.com/statuses/show/4452134416.xml curl http://twitter.com/statuses/show/4452466408.xml curl http://twitter.com/statuses/show/4349744308.xml The above payloads don't contain a "retweet_count" element yet and they probably will. Other than that we don't suspect any more major changes as we approach a full public launch. As always, though, we're open and solicitous of everyone's feedback. Thanks. -- Marcel Molina Twitter Platform Team http://twitter.com/noradio