YouTube Analytics API: Channel Reports

  • The YouTube Analytics API provides channel reports that measure user activity metrics, including video views, ratings, and subscriptions across various report types like video, playlist, and ad performance.

  • To retrieve reports, use the ids parameter with channel==MINE for the authenticated user's channel or channel==CHANNEL_ID for a specific channel, requiring ownership, while requests require OAuth 2.0 authorization with specific scopes for user activity and monetary data.

  • Report tables utilize dimensions for data categories (e.g., day, country), metrics for quantitative measurements (e.g., views, likes), and filters to refine data (e.g., country==US), allowing customization based on the required report type.

  • Playlist reports analyze user interactions within a channel's playlists, offering metrics like views, estimatedMinutesWatched, and playlistStarts, with options for geographic and time-based breakdowns, and specific filters, such as isCurated, that will be deprecated soon.

  • Certain reports have constraints such as maxResults limitations, required sorting, and restrictions on using certain metrics or dimensions together, like liveOrOnDemand and averageViewPercentage, while certain traffic sources and report types might not be supported.

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:

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: Estimated revenue and ad performance metrics are supported for channel reports. To access these metrics, your request must be authorized with the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope. Additionally, the authenticated user's channel must be a member of the YouTube Partner Program. Requesting monetary metrics for a channel that is not in the YouTube Partner Program results in a 403 Forbidden error.

In the report tables throughout this page, metrics marked with an asterisk (*) are monetary metrics that require this scope and monetization status.

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

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.

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

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