Hide

YouTube Analytics API: Content Owner Reports

This page identifies the different types of content owner reports that you can retrieve via the API. Also see the Sample API requests document, which provides the API queries you would use to retrieve many different reports.

Note: Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program.

Contents

  1. Overview
  2. Authorization
  3. Filters
  4. User activity and earnings reports
    1. Video reports
    2. Playlist reports
  5. Ad performance reports

Overview

Content owner reports aggregate metrics for all of the channels linked to a specified YouTube content owner. You can also filter content owner reports so that they only return data for a specific channel that the authenticated content owner manages.

Content owner reports fall into two general categories:

  • User activity and earnings reports

    These reports support metrics that measure user activity, such as the number of views or ratings that occurred on all of a content owner's channels or playlists (or only on a specific channel, playlist, or video). Several of these reports also support statistics that measure earnings and ad performance.

    While activity reports and earnings reports may seem like two separate types of reports, they are grouped together here because they use the same dimensions. (Dimensions are the criteria used to aggregate data, such as the date on which user activity occurred or the country where users were located.)

    Activity reports are listed in two groups below:

    • Video reports provide statistics for all user activity and earnings related to a content owner's videos.
    • Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist.

  • Ad performance reports

    These reports contain metrics related to revenue and ad performance, and they always use the adType dimension to group those 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.

To retrieve a content owner report, set the ids parameter value in your API request to contentOwner==OWNER_NAME, where OWNER_NAME specifies the content owner's ID. Ask your partner manager if you are unsure of the value.

Authorization

All YouTube Analytics API requests require authorization, and the Authorization guide explains how to use the OAuth 2.0 protocol to authorize your requests. As that guide explains, when you retrieve an authorization token, you specify a list of scopes to identify the resources that your application could access on the user's behalf. (You can only retrieve the authorization token if the user grants your application the ability to access those resources.)

The YouTube Analytics API uses two authorization scopes to retrieve metrics:

Scope Description
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 earnings and ad performance metrics.

Important: The authorization token that your application sends for any given API request must grant access to the resources that you are requesting. Any YouTube Analytics API request that retrieves earnings or ad performance metrics must use an authorization token that grants access using the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.

Filters

All API requests to retrieve content owner reports must filter data using either the video dimension, the channel dimension, the isCurated dimension, or a supported combination of the claimedStatus and uploaderType dimensions. (Supported combinations are listed in the uploaderType dimension's definition.)

The report descriptions in the next section identify the filters that can be used for any given report. In the descriptions, filters shown in parentheses are optional. For example, if a report lists video(,country) as a filtering option, then the report could either be filtered to only include data for a specific video or to only include data for a specific video in a specific country.

The API also supports the ability to specify multiple values for the video, playlist, and channel 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.

User activity and earnings reports

The sections below describe the different video and playlist reports that the API supports for content owners. Each description includes an overview of the report as well as a list of the report's dimensions, metrics, and filters. Some reports also identify supported sorting criteria and require you to specify a maximum number of results to return.

Video reports

Click the panels below to see descriptions of different types of activity reports that the API supports.

Note: Metrics that are marked with an asterisk (*) require an authorization token that grants access to the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.

Important: Filters listed in parentheses are optional. For example, for the filtering option claimedStatus(,uploaderType)(,country), the claimedStatus filter is required, and the uploaderType and country filters are both optional.

Basic stats

Basic user activity statistics (including subscriber counts)

This report provides statistics related to user actions on all of a content owner's channels. You can filter the report to only return data for a specific video or country. It can also be used to only retrieve statistics for claimed content, including claimed content uploaded by the content owner, third parties, or both. The report includes the subscribersGained and subscribersLost metrics.

Dimensions: [None]
Metrics: views, comments, favoritesAdded, favoritesRemoved, likes, dislikes, shares, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, subscribersGained, subscribersLost, earnings*, grossRevenue*, monetizedPlaybacks*, playbackBasedCpm*, impressions*, impressionBasedCpm*
Filters: video(,country)
video(,continent)
video(,subContinent)
channel(,country)
channel(,continent)
channel(,subContinent)
group(,country)
group(,continent)
group(,subContinent)
claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,continent)
uploaderType(,subContinent)

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.

Dimensions: [None]
Metrics: views, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses
Filters: video,province
channel,province
group,province
claimedStatus,province(,uploaderType)
uploaderType,province
Time-based

Activity for time periods (including subscriber counts)

This report provides statistics related to user actions on all of a content owner's channels for specific time intervals. You can filter the report to only return data for a specific video or country. The report includes the subscribersGained and subscribersLost metrics.

Dimensions: day or 7DayTotals or 30DayTotals or month
Metrics: views, comments, favoritesAdded, favoritesRemoved, likes, dislikes, shares, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, subscribersGained, subscribersLost, uniques, earnings*, grossRevenue*, monetizedPlaybacks*, playbackBasedCpm*, impressions*, impressionBasedCpm*
Filters: video(,country)
video(,continent)
video(,subContinent)
channel(,country)
channel(,continent)
channel(,subContinent)
group(,country)
group(,continent)
group(,subContinent)

User activity for specific time periods (including owned and claimed content)

This report provides statistics related to user actions on all of a content owner's content for specific time intervals. This report supports a different set of filters than the one that includes subscriber counts. It can be used to only retrieve statistics for claimed content, including claimed content uploaded by the content owner, third parties, or both.

Dimensions: day or 7DayTotals or 30DayTotals or month
Metrics: views, comments, favoritesAdded, favoritesRemoved, likes, dislikes, shares, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, uniques, earnings*, grossRevenue*, monetizedPlaybacks*, playbackBasedCpm*, impressions*, impressionBasedCpm*
Filters: claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,continent)
uploaderType(,subContinent)

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

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.

Dimensions: day
7DayTotals
30DayTotals
month
Metrics: views, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses
Filters: video,province
channel,province
group,province
claimedStatus,province(,uploaderType)
uploaderType,province
Geographic

User activity by country (including subscriber counts)

This report provides statistics related to user activity on a country-by-country basis for all of a content owner's channels. You can filter the report to only return data for a specific video or channel. This report includes the subscribersGained and subscribersLost metrics.

Dimensions: country
continent
subContinent
Metrics: views, comments, favoritesAdded, favoritesRemoved, likes, dislikes, shares, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, subscribersGained, subscribersLost, earnings*, grossRevenue*, monetizedPlaybacks*, playbackBasedCpm*, impressions*, impressionBasedCpm*
Filters: video
channel
group

User activity by country (including owned and claimed content)

This report provides statistics related to user activity on a country-by-country basis for all of a content owner's channels. The report supports a different set of filters than the one that includes subscriber counts. It can be used to only retrieve statistics for claimed content, including claimed content uploaded by the content owner, third parties, or both.

Dimensions: country
continent
subContinent
Metrics: views, comments, favoritesAdded, favoritesRemoved, likes, dislikes, shares, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, earnings*, grossRevenue*, monetizedPlaybacks*, playbackBasedCpm*, impressions*, impressionBasedCpm*
Filters: claimedStatus
uploaderType
claimedStatus,uploaderType

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.

Dimensions: province
Metrics: views, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses
Filters: video,country==US
channel,country==US
group,country==US
claimedStatus,country==US(,uploaderType)
uploaderType,country==US
Playback location

Video playback location report

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

Dimensions: insightPlaybackLocationType
day,insightPlaybackLocationType
Metrics: views,estimatedMinutesWatched
Filters: video(,country)
video(,province)
video(,continent)
video(,subContinent)
channel(,country)
channel(,province)
channel(,continent)
channel(,subContinent)
group(,country)
group(,province)
group(,continent)
group(,subContinent)
claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,province)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,province)
uploaderType(,continent)
uploaderType(,subContinent)

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 content owner's content. When retrieving this report, you must set the insightPlaybackLocationType filter to EMBEDDED.

Dimensions: insightPlaybackLocationDetail
Metrics: views, estimatedMinutesWatched
Filters: video,insightPlaybackLocationType==EMBEDDED(,country)
video,insightPlaybackLocationType==EMBEDDED(,province)
video,insightPlaybackLocationType==EMBEDDED(,continent)
video,insightPlaybackLocationType==EMBEDDED(,subContinent)
channel,insightPlaybackLocationType==EMBEDDED(,country)
channel,insightPlaybackLocationType==EMBEDDED(,province)
channel,insightPlaybackLocationType==EMBEDDED(,continent)
channel,insightPlaybackLocationType==EMBEDDED(,subContinent)
group,insightPlaybackLocationType==EMBEDDED(,country)
group,insightPlaybackLocationType==EMBEDDED(,province)
group,insightPlaybackLocationType==EMBEDDED(,continent)
group,insightPlaybackLocationType==EMBEDDED(,subContinent)
claimedStatus,insightPlaybackLocationType==EMBEDDED(,uploaderType)(,country)
claimedStatus,insightPlaybackLocationType==EMBEDDED(,uploaderType)(,province)
claimedStatus,insightPlaybackLocationType==EMBEDDED(,uploaderType)(,continent)
claimedStatus,insightPlaybackLocationType==EMBEDDED(,uploaderType)(,subContinent)
uploaderType,insightPlaybackLocationType==EMBEDDED(,country)
uploaderType,insightPlaybackLocationType==EMBEDDED(,province)
uploaderType,insightPlaybackLocationType==EMBEDDED(,continent)
uploaderType,insightPlaybackLocationType==EMBEDDED(,subContinent)
Sorting options: -views
-estimatedMinutesWatched
Traffic source

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.

Dimensions: insightTrafficSourceType
day,insightTrafficSourceType
Metrics: views, estimatedMinutesWatched
Filters: video(,country)
video(,province)
video(,continent)
video(,subContinent)
channel(,country)
channel(,province)
channel(,continent)
channel(,subContinent)
group(,country)
group(,province)
group(,continent)
group(,subContinent)
claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,province)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,province)
uploaderType(,continent)
uploaderType(,subContinent)

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 content owner'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 content owner's content.

Dimensions: insightTrafficSourceDetail
Metrics: views, estimatedMinutesWatched
Filters: video,insightTrafficSourceType(,country)
video,insightTrafficSourceType(,province)
video,insightTrafficSourceType(,continent)
video,insightTrafficSourceType(,subContinent)
channel,insightTrafficSourceType(,country)
channel,insightTrafficSourceType(,province)
channel,insightTrafficSourceType(,continent)
channel,insightTrafficSourceType(,subContinent)
group,insightTrafficSourceType(,country)
group,insightTrafficSourceType(,province)
group,insightTrafficSourceType(,continent)
group,insightTrafficSourceType(,subContinent)
claimedStatus,insightTrafficSourceType(,uploaderType)(,country)
claimedStatus,insightTrafficSourceType(,uploaderType)(,province)
claimedStatus,insightTrafficSourceType(,uploaderType)(,continent)
claimedStatus,insightTrafficSourceType(,uploaderType)(,subContinent)
uploaderType,insightTrafficSourceType(,country)
uploaderType,insightTrafficSourceType(,province)
uploaderType,insightTrafficSourceType(,continent)
uploaderType,insightTrafficSourceType(,subContinent)
Sorting options: -views
-estimatedMinutesWatched

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/OS

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 stemmed from a Google search or from a link to a related video.

Dimensions: deviceType
day,deviceType
Metrics: views, estimatedMinutesWatched
Filters: video(,country)(, operatingSystem)
video(,province)(, operatingSystem)
video(,continent)(, operatingSystem)
video(,subContinent)(, operatingSystem)
channel(,country)(, operatingSystem)
channel(,province)(, operatingSystem)
channel(,continent)(, operatingSystem)
channel(,subContinent)(, operatingSystem)
group(,country)(, operatingSystem)
group(,province)(, operatingSystem)
group(,continent)(, operatingSystem)
group(,subContinent)(, operatingSystem)
claimedStatus(,uploaderType)(,country)(, operatingSystem)
claimedStatus(,uploaderType)(,province)(, operatingSystem)
claimedStatus(,uploaderType)(,continent)(, operatingSystem)
claimedStatus(,uploaderType)(,subContinent)(, operatingSystem)
uploaderType(,country)(, operatingSystem)
uploaderType(,province)(, operatingSystem)
uploaderType(,continent)(, operatingSystem)
uploaderType(,subContinent)(, operatingSystem)

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.

Dimensions: operatingSystem
day,operatingSystem
Metrics: views, estimatedMinutesWatched
Filters: video(,country)(, deviceType)
video(,province)(, deviceType)
video(,continent)(, deviceType)
video(,subContinent)(, deviceType)
channel(,country)(, deviceType)
channel(,province)(, deviceType)
channel(,continent)(, deviceType)
channel(,subContinent)(, deviceType)
group(,country)(, deviceType)
group(,province)(, deviceType)
group(,continent)(, deviceType)
group(,subContinent)(, deviceType)
claimedStatus(,uploaderType)(,country)(, deviceType)
claimedStatus(,uploaderType)(,province)(, deviceType)
claimedStatus(,uploaderType)(,continent)(, deviceType)
claimedStatus(,uploaderType)(,subContinent)(, deviceType)
uploaderType(,country)(, deviceType)
uploaderType(,province)(, deviceType)
uploaderType(,continent)(, deviceType)
uploaderType(,subContinent)(, deviceType)

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.

Dimensions: operatingSystem,deviceType
day,operatingSystem,deviceType
Metrics: views, estimatedMinutesWatched
Filters: video(,country)
video(,province)
video(,continent)
video(,subContinent)
channel(,country)
channel(,province)
channel(,continent)
channel(,subContinent)
group(,country)
group(,province)
group(,continent)
group(,subContinent)
claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,province)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,province)
uploaderType(,continent)
uploaderType(,subContinent)
Demographic

Viewer demographics (age group and gender)

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

Dimensions: ageGroup,gender
Metrics: viewerPercentage
Filters: video(,country)
video(,province)
video(,continent)
video(,subContinent)
channel(,country)
channel(,province)
channel(,continent)
channel(,subContinent)
group(,country)
group(,province)
group(,continent)
group(,subContinent)
claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,province)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,province)
uploaderType(,continent)
uploaderType(,subContinent)
Social

Content sharing by platform

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

Dimensions: sharingService
Metrics: shares
Filters: video(,country)
video(,continent)
video(,subContinent)
channel(,country)
channel(,continent)
channel(,subContinent)
group(,country)
group(,continent)
group(,subContinent)
claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,continent)
uploaderType(,subContinent)
Audience retention

Audience retention during video playback

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.

Dimensions: elapsedVideoTimeRatio
Metrics: audienceWatchRatio, relativeRetentionPerformance
Filters: video(,audienceType)
group(,audienceType)
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 overall, by country, by continent, or by subcontinent (<= 200 results)

This report lists the content owner's top videos based on the specified filtering and sorting criteria.

Dimensions: video
Metrics: views, comments, favoritesAdded, favoritesRemoved, likes, dislikes, shares, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, subscribersGained, subscribersLost
Filters: channel(,country)
claimedStatus(,uploaderType)(,country)
uploaderType(,country)
channel(,continent)
claimedStatus(,uploaderType)(,continent)
uploaderType(,continent)
channel(,subContinent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,subContinent)
Sorting options: -views
-earnings
-estimatedMinutesWatched
-subscribersGained
-subscribersLost

Top videos overall, by country, by continent, or by subcontinent (<= 200 results)

This report lists the content owner'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.

Dimensions: video
Metrics: views, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses
Filters: channel(,province)
claimedStatus(,uploaderType)(,province)
uploaderType(,province)
Sorting options: -views
-earnings
-estimatedMinutesWatched
-subscribersGained
-subscribersLost

Playlist reports

Click the panels below to see descriptions of the playlist activity reports that the API supports.

Note: Metrics that are marked with an asterisk (*) require an authorization token that grants access to the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.

Important: Filters listed in parentheses are optional. For example, for the filtering option claimedStatus(,uploaderType)(,country), the claimedStatus filter is required, and the uploaderType and country filters are both optional.

Basic stats

Basic user activity statistics

This report provides statistics related to users' interactions with playlists on a content owner's channels. You can filter the report to only return data for a specific channel, playlist, or geographic region.

Dimensions: [None]
Metrics: views, estimatedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,playlist)(,country)
isCurated==1(,playlist)(,continent)
isCurated==1(,playlist)(,province)
isCurated==1(,playlist)(,subContinent)
isCurated==1(,channel)(,country)
isCurated==1(,channel)(,continent)
isCurated==1(,channel)(,province)
isCurated==1(,channel)(,subContinent)
isCurated==1(,group)(,country)
isCurated==1(,group)(,continent)
isCurated==1(,group)(,province)
isCurated==1(,group)(,subContinent)
Time-based

Playlist activity for time periods

This report provides playlist viewing statistics for all of a content owner's channels for specific time intervals. You can filter the report to only return data for a specific playlist, channel, or country.

Dimensions: day or 7DayTotals or 30DayTotals or month
Metrics: views, estimatedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,playlist)(,country)
isCurated==1(,playlist)(,continent)
isCurated==1(,playlist)(,province)
isCurated==1(,playlist)(,subContinent)
isCurated==1(,channel)(,country)
isCurated==1(,channel)(,continent)
isCurated==1(,channel)(,province)
isCurated==1(,channel)(,subContinent)
isCurated==1(,group)(,country)
isCurated==1(,group)(,continent)
isCurated==1(,group)(,province)
isCurated==1(,group)(,subContinent)
Geographic

User activity by geography

This report provides playlist viewing statistics for specific geographic regions for all of a content owner's channels. You can filter the report to only return data for a specific playlist or channel. This report includes the subscribersGained and subscribersLost metrics.

Dimensions: country
province
continent
subContinent
Metrics: views, estimatedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1
isCurated==1(,playlist)
isCurated==1(,channel)
isCurated==1(,group)
Playback location

Playlist playback location report

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

Dimensions: insightPlaybackLocationType
day,insightPlaybackLocationType
Metrics: views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,playlist)(,country)
isCurated==1(,playlist)(,continent)
isCurated==1(,playlist)(,province)
isCurated==1(,playlist)(,subContinent)
isCurated==1(,channel)(,country)
isCurated==1(,channel)(,continent)
isCurated==1(,channel)(,province)
isCurated==1(,channel)(,subContinent)
isCurated==1(,group)(,country)
isCurated==1(,group)(,continent)
isCurated==1(,group)(,province)
isCurated==1(,group)(,subContinent)

Playback location detail for playlists (<= 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 content owner's playlists. When retrieving this report, you must set the insightPlaybackLocationType filter to EMBEDDED and the isCurated filter to 1. The report supports the following optional filters as well:

  • You can use either the playlist filter or the channel filter to retrieve data for a particular playlist or channel. These two filters cannot be used together, but can be combined with one of the geographic filters described below.

  • You can filter the data for a particular geographic region by using either the country, province, continent, or subContinent filters. You cannot use more than one of these filters together, but you can combine a geographic filter with the playlist or channel content filters.

Dimensions: insightPlaybackLocationDetail
Metrics: views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1,insightPlaybackLocationType==EMBEDDED
isCurated==1,insightPlaybackLocationType==EMBEDDED(,channel)(,country)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,channel)(,province)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,channel)(,continent)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,channel)(,subContinent)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,playlist)(,country)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,playlist)(,province)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,playlist)(,continent)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,playlist)(,subContinent)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,group)(,country)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,group)(,province)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,group)(,continent)
isCurated==1,insightPlaybackLocationType==EMBEDDED(,group)(,subContinent)
Sorting options: -views
-estimatedMinutesWatched
-playlistStarts
Traffic source

Traffic source for playlists

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 or a channel page.

Dimensions: insightTrafficSourceType
day,insightTrafficSourceType
Metrics: views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,playlist)(,country)
isCurated==1(,playlist)(,continent)
isCurated==1(,playlist)(,province)
isCurated==1(,playlist)(,subContinent)
isCurated==1(,channel)(,country)
isCurated==1(,channel)(,continent)
isCurated==1(,channel)(,province)
isCurated==1(,channel)(,subContinent)
isCurated==1(,group)(,country)
isCurated==1(,group)(,continent)
isCurated==1(,group)(,province)
isCurated==1(,group)(,subContinent)

Traffic source detail for playlists (<= 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 content owner'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 content owner's playlists. The report supports the following optional filters as well:

  • You can use either the playlist filter or the channel filter to retrieve data for a particular playlist or channel. These two filters cannot be used together, but can be combined with one of the geographic filters described below.

  • You can filter the data for a particular geographic region by using either the country, province, continent, or subContinent filters. You cannot use more than one of these filters together, but you can combine a geographic filter with the playlist or channel content filters.

Dimensions: insightTrafficSourceDetail
Metrics: views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1,insightTrafficSourceType
isCurated==1,insightTrafficSourceType(,country)
isCurated==1,insightTrafficSourceType(,province)
isCurated==1,insightTrafficSourceType(,continent)
isCurated==1,insightTrafficSourceType(,subContinent)
isCurated==1,insightTrafficSourceType(,channel)(,country)
isCurated==1,insightTrafficSourceType(,channel)(,province)
isCurated==1,insightTrafficSourceType(,channel)(,continent)
isCurated==1,insightTrafficSourceType(,channel)(,subContinent)
isCurated==1,insightTrafficSourceType(,playlist)(,country)
isCurated==1,insightTrafficSourceType(,playlist)(,province)
isCurated==1,insightTrafficSourceType(,playlist)(,continent)
isCurated==1,insightTrafficSourceType(,playlist)(,subContinent)
isCurated==1,insightTrafficSourceType(,group)(,country)
isCurated==1,insightTrafficSourceType(,group)(,province)
isCurated==1,insightTrafficSourceType(,group)(,continent)
isCurated==1,insightTrafficSourceType(,group)(,subContinent)
Sorting options: -views
-estimatedMinutesWatched

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/OS

Device type for playlists

This report aggregates viewing statistics based on the device type that viewers used to watch your playlist content. For example, it identifies the number of views that occurred on mobile devices or game consoles.

Dimensions: deviceType
day,deviceType
Metrics: views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,country)(,channel)(,operatingSystem)
isCurated==1(,province)(,channel)(,operatingSystem)
isCurated==1(,continent)(,channel)(,operatingSystem)
isCurated==1(,subContinent)(,channel)(,operatingSystem)
isCurated==1(,country)(,playlist)(,operatingSystem)
isCurated==1(,province)(,playlist)(,operatingSystem)
isCurated==1(,continent)(,playlist)(,operatingSystem)
isCurated==1(,subContinent)(,playlist)(,operatingSystem)
isCurated==1(,country)(,group)(,operatingSystem)
isCurated==1(,province)(,group)(,operatingSystem)
isCurated==1(,continent)(,group)(,operatingSystem)
isCurated==1(,subContinent)(,group)(,operatingSystem)

Operating system for playlists

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.

Dimensions: operatingSystem
day,operatingSystem
Metrics: views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,country)(,channel)(,deviceType)
isCurated==1(,province)(,channel)(,deviceType)
isCurated==1(,continent)(,channel)(,deviceType)
isCurated==1(,subContinent)(,channel)(,deviceType)
isCurated==1(,country)(,playlist)(,deviceType)
isCurated==1(,province)(,playlist)(,deviceType)
isCurated==1(,continent)(,playlist)(,deviceType)
isCurated==1(,subContinent)(,playlist)(,deviceType)
isCurated==1(,country)(,group)(,deviceType)
isCurated==1(,province)(,group)(,deviceType)
isCurated==1(,continent)(,group)(,deviceType)
isCurated==1(,subContinent)(,group)(,deviceType)

Operating system and device type for playlists

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.

Dimensions: operatingSystem,deviceType
day,operatingSystem,deviceType
Metrics: views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,playlist)(,country)
isCurated==1(,playlist)(,continent)
isCurated==1(,playlist)(,province)
isCurated==1(,playlist)(,subContinent)
isCurated==1(,channel)(,country)
isCurated==1(,channel)(,continent)
isCurated==1(,channel)(,province)
isCurated==1(,channel)(,subContinent)
isCurated==1(,group)(,country)
isCurated==1(,group)(,continent)
isCurated==1(,group)(,province)
isCurated==1(,group)(,subContinent)
Demographic

Viewer demographics (age group and gender)

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

Dimensions: ageGroup,gender
Metrics: viewerPercentage
Filters: isCurated==1(,playlist)(,country)
isCurated==1(,playlist)(,continent)
isCurated==1(,playlist)(,province)
isCurated==1(,playlist)(,subContinent)
isCurated==1(,channel)(,country)
isCurated==1(,channel)(,continent)
isCurated==1(,channel)(,province)
isCurated==1(,channel)(,subContinent)
isCurated==1(,group)(,country)
isCurated==1(,group)(,continent)
isCurated==1(,group)(,province)
isCurated==1(,group)(,subContinent)
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.

Top playlists overall, by country, by continent, or by subcontinent (<= 200 results)

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

Dimensions: playlist
Metrics: views, estimatedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist
Filters: isCurated==1(,playlist)(,country)
isCurated==1(,playlist)(,continent)
isCurated==1(,playlist)(,province)
isCurated==1(,playlist)(,subContinent)
isCurated==1(,channel)(,country)
isCurated==1(,channel)(,continent)
isCurated==1(,channel)(,province)
isCurated==1(,channel)(,subContinent)
Sorting options: -views
-estimatedMinutesWatched
-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 aggregate metrics based on the types of ads that ran during video playbacks. The API returns two types of ad performance metrics:

  • Playback-based ad performance metrics group data based on the primary type of ad shown during a video playback. A single video playback may result in multiple ad impressions, and the primary ad type is typically the one that generates the most revenue.

    Playback-based ad performance metrics are:

  • Impression-based ad performance metrics group information based on ad types. Since these metrics account for each ad impression, they do not have a notion of a primary ad type.

    Impression-based ad performance metrics are:

Ad performance reports (supported parameters)

Dimensions: adType
Metrics: grossRevenue, primaryAdGrossRevenue, monetizedPlaybacks, playbackBasedCpm, impressions, impressionBasedCpm
Filters: country
continent
subContinent
video(,country)
video(,continent)
video(,subContinent)
group(,country)
group(,continent)
group(,subContinent)
claimedStatus(,uploaderType)(,country)
claimedStatus(,uploaderType)(,continent)
claimedStatus(,uploaderType)(,subContinent)
uploaderType(,country)
uploaderType(,continent)
uploaderType(,subContinent)