Hide

YouTube Analytics API: Content Owner Reports

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

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.

Report types

The API supports the following types of reports:

  • Video reports support metrics that measure user activity related to a content owner's videos. For example, these metrics include the number of views or ratings that occurred on all of a content owner's channels (or only on a specific channel or video). Several of these reports also support statistics that measure earnings and ad performance.

  • 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, 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.

Retrieving a report

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