YouTube

YouTube API v2.0 - Watch History

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

A user's watch history feed lists videos that the user has watched on the YouTube website. If the user had a YouTube login cookie and watched embedded videos on other websites, those videos will be listed in the feed as well. (It does not include videos that were viewed on mobile devices.) The feed's entries are ordered by the time that the user watched the video, beginning with the most recently watched video. If a user watched a video multiple times, the feed will contain a separate entry for each occurrence.

To retrieve a user's watch history feed, send an authenticated GET request to the following URL:

https://gdata.youtube.com/feeds/api/users/default/watch_history?v=2

Note: A user can only retrieve her own watch history feed, so an API request to retrieve a user's watch history feed must be authenticated by the user whose watch history feed is being requested. In addition, the watch history feed is only supported in API version 2 (and above).

A watch history feed entry differs from a standard video feed entry in the following ways:

  • A watch history feed entry tag contains a <category> tag that has a scheme attribute value of http://schemas.google.com/g/2005#kind and a term attribute value of http://gdata.youtube.com/schemas/2007#watchHistory. This tag identifies the entry as a watch history feed entry. In a standard video feed entry, this tag has a term attribute value of http://gdata.youtube.com/schemas/2007#video.

  • The <id> tag in the watch history feed entry contains a value that refers to the instance of the user watching the video. You can use the <yt:videoid> tag to retrieve the value that YouTube uses to uniquely identify the video.

  • In a watch history feed entry, the <published> and <updated> tags specify the time when the user watched the video. You can use the <yt:uploaded> tag to retrieve the time when the video was actually uploaded.

  • In a watch history feed entry, the <author> tag identifies the user who watched the video rather than the video uploader. You can use the <media:credit> tag to identify the video owner.

  • A watch history feed entry contains a <link> tag that points to the video.

It is also worth noting that in the watch history feed, as in other feeds, the <openSearch:totalResults> tag may overstate the actual number of results. As discussed in the reference guide, we recommend that you use a feed's <link> tags to identify pagination links for the previous and/or next page of entries in a feed.

Deleting videos from the watch history feed

To delete a video from a user's watch history feed, send a DELETE request to the edit URL for the appropriate watch history feed entry. This operation is only supported for authenticated users who are modifying their own watch history feed.

The request below shows the URL and format of an XML request to remove a video from the logged-in user's watch history feed:

DELETE /feeds/api/users/default/watch_history/WATCH_HISTORY_EVENT_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

To delete all videos from a user's watch history feed, send a POST request to https://gdata.youtube.com/feeds/api/users/default/watch_history/actions/clear. The request needs to include an empty <entry> element as shown in the example below:

POST /feeds/api/users/default/watch_history/actions/clear HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
</entry>
pagination links

« Previous
Video Recommendations
Next »
User Profiles and Accounts

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.