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:
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
schemeattribute value of
termattribute 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
termattribute value of
<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
<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.
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>