YouTube Analytics API: Content Owner Reports

  • Content Owner Reports provide YouTube content partners with detailed metrics on channels linked to their content owner accounts, covering user activity, ad performance, and estimated revenue.

  • These reports are accessible through the reports.query method using OAuth 2.0 authorization, and data must be filtered by dimensions like video, channel, or specific combinations of claimedStatus and uploaderType.

  • Video Reports offer a variety of data, including basic user activity, geographic breakdowns by country, province, and city, and time-based activity, all supporting a wide range of metrics like views, likes, and estimatedRevenue.

  • Playlist Reports, while deprecating the isCurated dimension by the end of 2024, offer metrics for both aggregated video activity and in-playlist activity, with the views metric behavior changing based on the presence or absence of isCurated.

  • Several reports require you to specify exactly one of playlist or group if certain view-related metrics are requested, and there are specific reports with their own requirements, like the Top Playlists report that can be sorted by playlistViews, playlistEstimatedMinutesWatched, or playlistStarts with a maxResults limit of 200.

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

This page lists reports that content owners can retrieve with the YouTube Analytics API. Content owner reports contain metrics for channels linked to a specified YouTube content owner. Metrics are individual measurements of user activity, ad performance, or estimated revenue.

  • Video reports contain user activity, ad performance, and estimated revenue metrics for videos on a content owner's channels.

  • Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist. Playlist reports use many of the same dimensions and filters as video reports.

  • 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 content owner report, call the API's reports.query method and set the ids parameter value in the 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 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:

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 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: 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.

Filters

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

The tables that explain the supported reports 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.

Understanding report tables

This section explains the formatting and terminology used in the tables that define reports that the API supports. The following table lists the dimensions, metrics, and filters supported for the playback details video report using the time dimension and the averageViewPercentage metric.

Property Value
Dimensions:
Use 0 or more creatorContentType, subscribedStatus, youtubeProduct
Use 0 or 1 day, month
Metrics:
Use 1 or more engagedViews, 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

The table contains two rows for dimensions, one row for metrics, and three 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=day,subscribedStatus
  • dimensions=month,subscribedStatus,youtubeProduct
  • dimensions=month,youtubeProduct

However, the parameter value day,month is invalid because it uses two time-based dimensions, and the request must use either 0 or 1.

While report tables define supported dimensions, metrics, and filters, the API enforces cross-parameter constraints. Querying unsupported or mutually exclusive combinations (such as combining incompatible geographic filters or omitting required parameters) causes an HTTP 400 badRequest error with the message The query is not supported. Review individual report tables on this page for specific restrictions that apply to each report.

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.
Important: All API requests to retrieve content owner video reports must filter data using either the video dimension, the channel dimension, the group dimension, or a supported combination of the claimedStatus and uploaderType dimensions. (Some reports do not support all of those options.) The supported combinations, which are also listed in the uploaderType dimension's definition, are:
  • uploaderType==self
  • claimedStatus==claimed
  • claimedStatus==claimed;uploaderType==self
  • claimedStatus==claimed;uploaderType==thirdParty

Video reports

Basic stats

Basic 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.

Property Value
Dimensions:
[None]
Metrics:
Use 1 or more engagedViews, 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 exactly 1 video, channel, group, or a supported combination of uploaderType and claimedStatus
Use 0 or 1 country, continent, subContinent

Basic 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.

Property Value
Dimensions:
[None]
Metrics:
Use 1 or more engagedViews, views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filters:
Use exactly 1 video, channel, group, or a supported combination of uploaderType and claimedStatus
Required province

Time-based

Activity for time periods

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.

Property Value
Dimensions:
Use exactly 1 day, month
Optional creatorContentType
Metrics:
Use 1 or more engagedViews, 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,