YouTube Analytics API: Channel Reports

This page lists reports that channel owners can retrieve with the YouTube Analytics API. Channel reports provide user activity metrics for a specified channel and measure things like video views, ratings, and subscription counts.

  • Video reports provide statistics for all user activity related to a channel's videos.
  • Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist.
  • Ad performance reports contain metrics related to revenue and ad performance. They use the adType dimension to group metrics based on the types of ads that ran during video playbacks. The ad performance reports section explains the two types of ad performance metrics that the API supports.

Retrieving a report

To retrieve a channel report, you must set the ids parameter value in your API request to one of the following values:

  • channel==MINE – The API returns data for the authenticated user's YouTube channel.

  • channel==CHANNEL_ID – Set CHANNEL_ID to the unique channel ID of the channel for which you are retrieving data. The user authorizing the request must be the owner of the channel.

    The channel ID is currently a string that begins with the letters UC, though its format is subject to change. (You can find your channel's ID on the advanced account settings page for your YouTube channel, or you can retrieve your channel's ID programmatically using the YouTube Data API's channels.list method.)

Authorization

All YouTube Analytics API requests must be authorized. The Authorization guide explains how to use the OAuth 2.0 protocol to retrieve authorization tokens.

YouTube Analytics API requests use the following authorization scopes:

Scopes
https://www.googleapis.com/auth/yt-analytics.readonly View YouTube Analytics reports for your YouTube content. This scope provides access to user activity metrics, like view counts and rating counts.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly View YouTube Analytics monetary reports for your YouTube content. This scope provides access to user activity metrics and to estimated revenue and ad performance metrics.
https://www.googleapis.com/auth/youtube Manage your YouTube account. In the YouTube Analytics API, channel owners use this scope to manage YouTube Analytics groups and group items.
https://www.googleapis.com/auth/youtubepartner View and manage YouTube assets and associated content on YouTube. In the YouTube Analytics API, content owners use this scope to manage YouTube Analytics groups and group items.

Note: Estimated revenue and ad performance metrics are not currently supported for channel reports. As a result, the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope does not currently grant access to monetary data in those reports.

Filters

The tables that explain the supported reports identify the filters that can be used for each report. In the tables, filters shown in parentheses are optional. For example, for the filtering option video(,country), the video filter is required, and the country filter is optional.

The API also supports the ability to specify multiple values for the video and playlist filters. If you do specify multiple values for one of these filters, you can also add that filter to the list of dimensions that you specify for the request. This is true even if the filter is not listed as a supported dimension for a particular report.

See the filters parameter definition for a complete explanation of how to filter API results for a specific value or set of values.

Understanding report tables

This section explains the formatting and terminology used in the tables that define reports that the API supports. The table below lists the dimensions, metrics, and filters supported for time-based, channel playlist reports:

Contents
Dimensions:
Use exactly 1 day, 7DayTotals, 30DayTotals, month
Use 0 or more subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more subscribedStatus, youtubeProduct

The table contains two rows for dimensions, one row for metrics, and four rows for filters. For dimensions and filters, values from each row can be combined in an API request as long as the combination follows the usage rules in the table. So, for example, valid dimensions parameter values for this report include:

  • dimensions=day
  • dimensions=7DayTotals,subscribedStatus
  • dimensions=30DayTotals,subscribedStatus,youtubeProduct
  • dimensions=month,youtubeProduct

However, the parameter value day,month is invalid because it uses two time-based dimensions, but the request must use exactly 1. In this case, the parameter value subscribedStatus,youtubeProduct does actually return a report, but metrics are not aggregated by day, week, month, etc. (That report is documented separately in the documentation.)

Report table terminology

Tables use the following terminology to indicate whether dimensions are required or optional:

  • These terms mean a value is required:
    • Required: You must include the value.
    • Use exactly 1: You must include one value from the group.
    • Use 1 or more: You can include any or all values from the group, but you must include at least one.
  • These terms mean a value is optional:
    • Optional: You have the option of include the value.
    • Use 0 or 1: You have the option of including one value from the group.
    • Use 0 or more: You have the option of including any or all values from the group.

Video reports

Basic stats

Basic user activity statistics

This report provides statistics related to users' actions on a channel. You can filter the report to only return data for a specific video or country.

Contents
Dimensions:
[None]
Metrics:
Use 1 or more views, redViews, comments, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks, subscribersGained, subscribersLost, estimatedRevenue*, estimatedAdRevenue*, grossRevenue*, estimatedRedPartnerRevenue*, monetizedPlaybacks*, playbackBasedCpm*, adImpressions*, cpm*
Filters:
Use 0 or 1 country, continent, subContinent
Use 0 or 1 video, group

Basic user activity statistics for U.S. states

This report provides statistics for a particular U.S. state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.

Contents
Dimensions:
[None]
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Required province
Use 0 or 1 video, group

Time-based

User activity by country for specific time periods

This report provides statistics related to user actions on a channel for specific time intervals. You can filter the report to only return data for a specific video or country.

Contents
Dimensions:
Use exactly 1 day, 7DayTotals, 30DayTotals, month
Metrics:
Use 1 or more views, redViews, comments, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks, subscribersGained, subscribersLost, uniques, estimatedRevenue*, estimatedAdRevenue*, grossRevenue*, estimatedRedPartnerRevenue*, monetizedPlaybacks*, playbackBasedCpm*, adImpressions*, cpm*
Filters:
Use 0 or 1 country, continent, subContinent
Use 0 or 1 video, group

User activity in U.S. states for specific time periods

This report provides statistics related to user activity for a particular U.S. state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.

Contents
Dimensions:
Use exactly 1 day, 7DayTotals, 30DayTotals, month
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Required province
Use 0 or 1 video, group

User geography

User activity by country

This report provides statistics related to user activity on a country-by-country basis for a channel. You can filter the report to only return data for a specific video.

Contents
Dimensions:
Required country
Metrics:
Use 1 or more views, redViews, comments, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks, subscribersGained, subscribersLost, estimatedRevenue*, estimatedAdRevenue*, grossRevenue*, estimatedRedPartnerRevenue*, monetizedPlaybacks*, playbackBasedCpm*, adImpressions*, cpm*
Filters:
Use 0 or 1 continent, subContinent
Use 0 or 1 video, group

User activity by province

This report provides user activity statistics for U.S. states and the District of Columbia. For this report, you must set the filters parameter value to country==US.

Contents
Dimensions:
Required province
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Required country==US
Use 0 or 1 video, group

Playback details

Playback detail reports provide statistics related to the following viewing attributes:

  • Was the view of a live video broadcast or an on-demand video?
  • Was the viewer subscribed to the channel that owns the video?
  • On which YouTube product did the view occur?

Note: The liveOrOnDemand dimension and filter cannot be used in conjunction with the averageViewPercentage metric. As such, each of the following subsections lists two reports. One report supports the liveOrOnDemand dimension (and filter), while the other supports the averageViewPercentage metric.

User activity by subscribed status

This report provides user activity metrics for subscribed and unsubscribed viewers. Statistics can be grouped by time period (day, 7DayTotals, 30DayTotals, or month), and the report can also be filtered by country, continent, or subContinent.

Contents
Dimensions:
Optional subscribedStatus
Use 0 or 1 day, 7DayTotals, 30DayTotals, month
Metrics:
Use 1 or more views, redViews, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Use 0 or 1 country, continent, subContinent
Use 0 or 1 video, group
Optional subscribedStatus

User activity by subscribed status for provinces

This report provides user activity metrics for subscribed and unsubscribed viewers in U.S. states or the District of Columbia. This report supports fewer metrics than the previous report.

Contents
Dimensions:
Optional subscribedStatus
Use 0 or 1 day, 7DayTotals, 30DayTotals, month
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Use 0 or 1 video, group
Use 0 or more province, subscribedStatus

Playback details with optional time dimension

The time dimension – day, 7DayTotals, 30DayTotals, or month – is optional for these reports because, regardless, you need to use the start-date and end-date request parameters to specify the date range that the report will cover. The dimension, if present, indicates that you want data in the report to be aggregated by day, month, etc.

Playback details with optional time dimension and liveOrOnDemand statistics

This report provides playback detail statistics for specific time intervals. It supports the liveOrOnDemand dimension (and filter).

Contents
Dimensions:
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Use 0 or 1 day, 7DayTotals, 30DayTotals, month
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Playback details with optional time dimension and averageViewPercentage metric

This report provides playback detail statistics for specific time intervals. It supports the averageViewPercentage metric.

Contents
Dimensions:
Use 0 or more subscribedStatus, youtubeProduct
Use 0 or 1 day, 7DayTotals, 30DayTotals, month
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more subscribedStatus, youtubeProduct

Playback details by country

Playback details by country with liveOrOnDemand statistics

This report provides playback detail statistics on a country-by-country basis. It supports the liveOrOnDemand dimension (and filter).

Contents
Dimensions:
Required country
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration
Filters:
Use 0 or 1 continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Playback details by country with averageViewPercentage metric

The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.

Contents
Dimensions:
Required country
Use 0 or more subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage
Filters:
Use 0 or 1 continent, subContinent
Use 0 or 1 video, group
Use 0 or more subscribedStatus, youtubeProduct

Playback details by province

Playback details by province with liveOrOnDemand statistics

This report provides playback detail statistics for U.S. states and the District of Columbia. It supports the liveOrOnDemand dimension (and filter).

Contents
Dimensions:
Required province
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration
Filters:
Required country==US
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Playback details by province with averageViewPercentage metric

The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.

Contents
Dimensions:
Required province
Use 0 or more subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage
Filters:
Required country==US
Use 0 or 1 video, group
Use 0 or more subscribedStatus, youtubeProduct

Playback locations

Video playback location report

This report provides statistics related to the type of page or application where video playbacks occurred.

Contents
Dimensions:
Required insightPlaybackLocationType
Use 0 or more day, liveOrOnDemand, subscribedStatus
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus

Playback location detail (<= 25 results)

Note: This report requires you to set the max-results parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

This report identifies the embedded video players that generated the most views or viewing time for a channel's videos.

Contents
Dimensions:
Required insightPlaybackLocationDetail
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched
Filters:
Required insightPlaybackLocationType==EMBEDDED
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

Traffic sources

Traffic source

This report aggregates viewing statistics based on the manner in which viewers reached your video content. For example, it identifies the number of views that stemmed from a Google search or from a link to a related video.

Contents
Dimensions:
Required insightTrafficSourceType
Use 0 or more day, liveOrOnDemand, subscribedStatus
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus

Traffic source detail (<= 25 results)

Note: This report requires you to set the max-results parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

This report aggregates viewing statistics based on the referrers that generated the most views for the channel's content. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available. For example, if you set the insightTrafficSourceType filter to ADVERTISING, the report will list the types of ads that generated the most views or viewing time for the channel's content.

Contents
Dimensions:
Required insightTrafficSourceDetail
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched
Filters:
Required insightTrafficSourceType (see note below table)
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

Note: This report is only supported for specific traffic sources. For example, the NO_LINK_EMBEDDED traffic source does not have additional details and, therefore, does not support this report. See the insightTrafficSourceType definition for details about which traffic sources support this report.

Device type and operating system

Device type

This report aggregates viewing statistics based on the manner in which viewers reached your video content. For example, it identifies the number of views that occurred on mobile devices or game consoles.

Contents
Dimensions:
Required deviceType
Use 0 or more day, liveOrOnDemand, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more operatingSystem, liveOrOnDemand, subscribedStatus, youtubeProduct

Operating system

This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of views that occurred on Android devices or on PlayStations.

Contents
Dimensions:
Required operatingSystem
Use 0 or more day, liveOrOnDemand, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more deviceType, liveOrOnDemand, subscribedStatus, youtubeProduct

Operating system and device type

This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies the number of views that occurred on Android tablets or on Windows desktop devices.

Contents
Dimensions:
Required deviceType, operatingSystem
Use 0 or more day, liveOrOnDemand, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct

Viewer demographics

This report aggregates viewing statistics based on viewers' age group and gender.

Contents
Dimensions:
Use 1 or more ageGroup, gender
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more viewerPercentage
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 video, group
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Note: The viewerPercentage values in this report are not normalized for different values or combinations of values for playback detail dimensions (subscribedStatus, liveOrOnDemand, or youtubeProduct).

For example, a report that uses the subscribedStatus dimension returns viewerPercentage data adding up to 100 percent for subscribed views and viewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)

You can use filters to ensure that the report only contains viewerPercentage data for one value (or combination of values) for playback detail dimensions.

Engagement and content sharing

This report provides statistics showing how frequently the channel's videos were shared on different social platforms.

Contents
Dimensions:
Required sharingService
Optional subscribedStatus
Metrics:
Use 1 or more shares
Filters:
Use 0 or 1 country, continent, subContinent
Use 0 or 1 video, group
Optional subscribedStatus

Audience retention

This report measures a video's ability to retain its audience. The elapsedVideoTimeRatio dimension measures the amount of the video that has elapsed for the corresponding metric values. The audienceWatchRatio and relativeRetentionPerformance metrics provide two measurements that show how well the video retains its audience. The first is an absolute value, while the second shows how the video performs relative to other YouTube videos of a similar length.

Note: Audience retention reports do not support the ability to specify a comma-separated list of values for the video filter; the value must specify a single video ID.

Contents
Dimensions:
Required elapsedVideoTimeRatio
Metrics:
Use 1 or more audienceWatchRatio, relativeRetentionPerformance
Filters:
Required video
Use 0 or more audienceType, subscribedStatus, youtubeProduct

Top videos

Note: These reports require you to set the max-results parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 videos. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.

Top videos with optional regional filters (<= 200 results)

This report lists the channel's top videos. The report can be filtered to list top videos by country, continent, or subContinent.

Contents
Dimensions:
Required video
Metrics:
Use 1 or more views, redViews, comments, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks, subscribersGained, subscribersLost, estimatedRevenue*, estimatedAdRevenue*, grossRevenue*, estimatedRedPartnerRevenue*, monetizedPlaybacks*, playbackBasedCpm*, adImpressions*, cpm*
Filters:
Use 0 or 1 country, continent, subContinent
Sorting options: -views
-redViews
-estimatedRevenue
-estimatedRedPartnerRevenue
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-subscribersGained
-subscribersLost

Top videos by state (<= 200 results)

This report lists the channel's top videos in a particular U.S. state or the District of Columbia. Note that this report only supports a subset of the metrics available in the country-specific report described above.

Contents
Dimensions:
Required video
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Required province
Optional subscribedStatus
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

Top videos for subscribed or unsubscribed viewers(<= 200 results)

This report lists the channel's top videos for subscribed or unsubscribed viewers. The report can be filtered to list top videos by country, continent, or subContinent. The previous report lets you retrieve the top videos in a particular U.S. state for subscribed or unsubscribed viewers, but it supports fewer metrics than this report.

Contents
Dimensions:
Required video
Metrics:
Use 1 or more views, redViews, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Optional subscribedStatus
Use 0 or 1 country, continent, subContinent
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

Top videos by YouTube Product (<= 200 results)

This report lists the channel's top videos and supports playback detail and geographic filters. This report is similar to the previous one, but it supports fewer metrics and adds support for the youtubeProduct filter.

Contents
Dimensions:
Required video
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or more subscribedStatus, youtubeProduct
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

Top videos with playback detail filters (<= 200 results)

This report lists the channel's top videos, filtering by any or all of the playback detail dimensions: liveOrOnDemand, subscribedStatus, and youtubeProduct. Unlike the previous report, this one supports the liveOrOnDemand filter and does not support the averageViewPercentage metric.

Contents
Dimensions:
Required video
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration
Filters:
Use 0 or 1 country, province, continent, subContinent
Use 0 or more liveOrOnDemand, subscribedStatus, youtubeProduct
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched

Playlist reports

Basic stats

This report provides statistics related to users' interactions with a channel's playlists. You can filter the report to only return data for a specific playlist or country.

Contents
Dimensions:
[None]
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more subscribedStatus, youtubeProduct

Time-based

This report provides statistics related to users' interactions with a channel's playlists. You can filter the report to only return data for a specific playlist or country.

Contents
Dimensions:
Use exactly 1 day, 7DayTotals, 30DayTotals, month
Use 0 or more subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more subscribedStatus, youtubeProduct

User geography

Playlist activity by country

This report provides statistics related to users' interactions with a channel's playlists. You can filter the report to only return data for a specific playlist, group of playlists, or country.

Contents
Dimensions:
Required country
Use 0 or more subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more subscribedStatus, youtubeProduct

Playlist activity by province

This report provides playlist activity statistics for U.S. states and the District of Columbia. For this report, you include country==US in the the filters parameter value.

Contents
Dimensions:
Required province
Use 0 or more subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1;country==US
Use 0 or 1 playlist, group
Use 0 or more subscribedStatus, youtubeProduct

Playback locations

This report provides statistics related to the type of page or application where playlist playbacks occurred.

Contents
Dimensions:
Required insightPlaybackLocationType
Use 0 or more day, subscribedStatus
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Optional subscribedStatus

Playback location detail (<= 25 results)

Note: This report requires you to set the max-results parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

This report identifies the embedded video players that generated the most views or viewing time for a channel's playlists.

Contents
Dimensions:
Required insightPlaybackLocationDetail
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1;insightPlaybackLocationType==EMBEDDED
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Optional subscribedStatus
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-playlistStarts

Traffic sources

This report aggregates viewing statistics based on the manner in which viewers reached your playlist content. For example, it identifies the number of views that stemmed from a Google search.

Contents
Dimensions:
Required insightTrafficSourceType
Use 0 or more day, subscribedStatus
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Optional subscribedStatus

Traffic source detail (<= 25 results)

Note: This report requires you to set the max-results parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

This report aggregates viewing statistics based on the referrers that generated the most views for the channel's playlists. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available.

For example, if you set the insightTrafficSourceType filter to ADVERTISING, the report will list the types of ads that generated the most views or viewing time for the channel's playlists.

Contents
Dimensions:
Required insightTrafficSourceDetail
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1;insightTrafficSourceType
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Optional subscribedStatus
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-playlistStarts

Note: This report is only supported for specific traffic sources. For example, the NO_LINK_EMBEDDED traffic source does not have additional details and, therefore, does not support this report. See the insightTrafficSourceType definition for details about which traffic sources support this report.

Device type and operating system

Device type

This report aggregates viewing statistics based on the manner in which viewers reached your playlist content. For example, it identifies the number of views that occurred on mobile devices or game consoles.

Contents
Dimensions:
Required deviceType
Use 0 or more day, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more operatingSystem, subscribedStatus, youtubeProduct

Operating system

This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of playlist views that occurred on Android devices or on PlayStations.

Contents
Dimensions:
Required operatingSystem
Use 0 or more day, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more deviceType, subscribedStatus, youtubeProduct

Operating system and device type

This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies the number of playlist views that occurred on Android tablets or on Windows desktop devices.

Contents
Dimensions:
Required deviceType, operatingSystem
Use 0 or more day, subscribedStatus, youtubeProduct
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more subscribedStatus, youtubeProduct

Viewer demographics

Contents
Dimensions:
Use 1 or more ageGroup, gender
Use 0 or more subscribedStatus, youtubeProduct
Metrics:
Required viewerPercentage
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or 1 playlist, group
Use 0 or more subscribedStatus, youtubeProduct
Note: The viewerPercentage values in this report are not normalized for different values or combinations of values for playback detail dimensions (subscribedStatus and youtubeProduct).

For example, a report that uses the subscribedStatus dimension returns viewerPercentage data adding up to 100 percent for subscribed views and viewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)

You can use filters to ensure that the report only contains viewerPercentage data for one value (or combination of values) for playback detail dimensions.

Top playlists

Note: These reports require you to set the max-results parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 playlists. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.

This report lists the channel's top playlists based on the specified filtering and sorting criteria.

Contents
Dimensions:
Required playlist
Metrics:
Use 1 or more views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters:
Required isCurated==1
Use 0 or 1 country, province, continent, subContinent
Use 0 or more playlist, subscribedStatus, youtubeProduct
Sorting options: -views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-playlistStarts

Ad performance reports

Note: Ad performance reports require an authorization token that grants access to the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.

Ad performance reports provide impression-based metrics for ads that ran during video playbacks. These metrics account for each ad impression, and each video playback can yield multiple impressions.

The impression-based ad performance metrics are:

In addition, some video reports support the following playback-based ad performance metrics. However, these metrics are not included in ad performance reports.

Ad performance by ad type

Contents
Dimensions:
Required adType
Optional day
Metrics:
Use 1 or more grossRevenue, adImpressions, cpm
Filters:
Use 0 or 1 video, group
Use 0 or 1 country, continent, subContinent