Core metrics

While the YouTube Reporting API is subject to the Deprecation Policy defined in the Terms of Service, non-core metrics (and non-core dimensions) are not subject to the policy. In the definitions on this page, any metric that is a core metric is explicitly identified as such.

The list below identifies the API's core metrics.
Any of these metrics that are also used in the YouTube Analytics API are also core metrics in that API.

View metrics

views(core metric)

The number of times that a video was viewed. In a playlist report, the metric indicates the number of times that a video was viewed in the context of a playlist. The YouTube Help Center provides additional information about how views are reported. This is a core metric and is subject to the Deprecation Policy.

red_views

The number of times that a video was viewed by YouTube Red members.

views_percentage(core metric)

The percentage of viewers who were logged in when watching the video or playlist. This is a core metric and is subject to the Deprecation Policy.

Watch time metrics

watch_time_minutes(core metric)

The number of minutes that users watched videos for the specified channel, content owner, video, or playlist. This is a core metric and is subject to the Deprecation Policy.

red_watch_time_minutes

The number of minutes that YouTube Red members watched a video.

average_view_duration_seconds(core metric)

The average length, in seconds, of video playbacks. In a playlist report, the metric indicates the average length, in seconds, of video playbacks that occurred in the context of a playlist. This is a core metric and is subject to the Deprecation Policy.

The number of times that users indicated that they liked a video by giving it a positive rating. This is a core metric and is subject to the Deprecation Policy.

dislikes(core metric)

The number of times that users indicated that they disliked a video by giving it a negative rating. This is a core metric and is subject to the Deprecation Policy.

shares(core metric)

The number of times that users shared a video through the Share button. See the YouTube Help Center for more information. This is a core metric and is subject to the Deprecation Policy.

subscribers_gained(core metric)

The number of times that users subscribed to a channel. This is a core metric and is subject to the Deprecation Policy.

Channels can gain or lose subscribers in several places, including the video watch page, the channel page, and the guide that appears on the YouTube home page.
To identify the number of new channel subscribers who did not subscribe through a video watch page, a basic user activity report contains a row that does not specify a video_id dimension value. That row also specifies a value for the subscribersLost metric, but it does not specify values for other metrics.

subscribers_lost(core metric)

The number of times that users unsubscribed from a channel. This is a core metric and is subject to the Deprecation Policy.

Data for this metric is reported similarly to the subscribers_gained metric.
To identify the number of users who unsubscribed but did not unsubscribe on a video watch page, a basic user activity report contains a row that does not specify a video_id dimension value. That row also specifies a value for the subscribers_gained metric, but it does not specify values for other metrics.

videos_added_to_playlists

The number of times that videos were added to any YouTube playlists. The videos could have been added to the video owner's playlist or to other channels' playlists.

The metric value does include the number of times that videos were added to default playlists like the "Watch Later" playlist. However, it does not count playlists that a video is automatically added to, such as a channel's uploads playlist or a user's watch history.

This metric returns an absolute number, meaning that if a user adds a video to a playlist, removes it, and then adds it again, the metric value reflects the video being added to a playlist twice. Data for this metric is not available for dates before October 1, 2014.

videos_removed_from_playlists

The number of times that videos were removed from any YouTube playlists. The videos could have been removed from the video owner's playlist or from other channels' playlists.

The metric value includes the number of times that videos were removed from default playlists like the "Watch Later" playlist.

This metric returns an absolute number, meaning that if a user adds a video to a playlist, removes it, adds it again, and then removes it again, the metric value reflects the video being removed from a playlist twice. Data for this metric is not available for dates before October 1, 2014.

Playlist metrics

playlist_starts

The number of times that viewers initiated playback of a playlist. Note that this metric only includes playlist views that occurred on the web.

playlist_saves_added(only supported in YouTube Reporting API)

The number of times that users saved a playlist. See the YouTube Help Center for more information about saved playlists. This metric returns an absolute number, meaning that if a user saves a playlist, removes it from the list of saved playlists, and saves it again, the metric value reflects two playlist saves being added.

playlist_saves_removed(only supported in YouTube Reporting API)

The number of times that users removed the playlist from their lists of saved playlists. This metric returns an absolute number, meaning that if a user saves a playlist, removes it from the list of saved playlists, saves it again, and removes it again, the metric value reflects two playlist saves being removed.

The number of end screen elements that were displayed. One impression is logged for each end screen element that displays.

end_screen_element_clicks

The number of times that end screen elements were clicked.

end_screen_element_click_rate

The click-through-rate for end screen elements, which is calculated as the ratio of end screen element clicks to end screen element impressions.

Audience retention metrics

audience_retention_percentage

The absolute ratio of viewers watching the video at the given point in the video. The ratio is calculated by comparing the number of times a portion of a video has been watched to the total number of views of the video. The elapsed_video_time_percentage dimension identifies the portion of the video to which the metric corresponds.

Note that a portion of a video could be watched more than once (or not at all) in a given video view. For example, if users rewind and watch the same portion of a video multiple times, then the absolute ratio for that portion of the video the could be greater than 1.

The following examples illustrate how the value is calculated:

A one-minute video is watched 100 times. Half of the viewers stop watching after 15 seconds and the rest watch the entire video. None of the viewers watch any parts of the video more than once. In this case, this metric's value would be 1 for time buckets in the first quarter of the video, and its value would be 0.50 for the remainder of the video.

A one-minute video is watched 100 times. All of the viewers watch the entire video, but 20 of the viewers watch until the video's 45-second mark, then skip back to the video's 30-second mark, and then watch the remainder of the video. In this case, the metric's value would be 1 for time buckets in either the first half or the last quarter of the video. However, the value would be 1.2 for time buckets in the third quarter of the video since 100 percent of the viewers watched that segment of the video but 20% of those viewers watched the segment twice.

Estimated revenue metrics

Note: Estimated revenue metrics are subject to month-end adjustments and do not include partner-sold and partner-served advertising. Please see the YouTube Help Center for additional information and notes about estimated revenue figures.

The YouTube Reporting API reports all estimated revenue and earnings figures in USD.

estimated_partner_revenue(core metric)

The total estimated net revenue from all Google-sold advertising sources as well as from non-advertising sources for the selected date range and region.

estimated_partner_ad_revenue

The total estimated net revenue from all Google-sold advertising sources for the selected date range and region.

Estimated revenue metrics are subject to month-end adjustment and do not include partner-sold and partner-served advertising.

The total estimated earnings (net revenue) from auction-sold AdSense advertising for the selected date range and region.Note: This metric has been renamed and is called estimated_partner_ad_auction_revenue in the most current versions of all reports that contain it.

The total estimated earnings (net revenue) from reserved-sold advertising via DoubleClick (DCLK) and other YouTube-sold sources. This metric was previously named estimated_partner_double_click_revenue.

The total estimated earnings (net revenue) from reserved-sold advertising via DoubleClick (DCLK) and other YouTube-sold sources.Note: This metric has been renamed and is called estimated_partner_ad_reserved_revenue in the most current versions of all reports that contain it.

The total estimated revenue from transactions, such as paid content and Fan Funding, minus any partner-charged refunds.

Ad performance metrics

estimated_youtube_ad_revenue

The estimated gross revenue, in USD, from all Google-sold or DoubleClick-partner-sold advertising for the selected date range and region. Gross revenue is subject to month-end adjustment and does not include partner-served advertising. Gross revenue should not be confused with estimated revenue, or net revenue, which factors in your share of ownership and revenue-sharing agreements.

estimated_cpm

The estimated gross revenue per thousand ad impressions.

ad_impressions

The number of verified ad impressions served.

estimated_monetized_playbacks

The number of instances when a viewer played your video and was shown at least one ad impression. A monetized playback is counted if a viewer is shown a preroll ad but quits watching the ad before your video ever starts. The expected estimated error for this figure is ±2.0%.