API Reference

The YouTube Analytics API allows you to retrieve YouTube Analytics data for a YouTube channel or content owner. The API supports real-time queries and generates a report based on the API request parameters.

The API supports two types of functions:

  • Report retrieval – The API's reports.query method retrieves YouTube Analytics reports.

  • YouTube Analytics group management – A YouTube Analytics group is a custom collection of up to 500 channels, videos, playlists, or assets. The API supports several methods to create, retrieve, and update YouTube Analytics groups. Channel and content owners can then use the reports.query method to retrieve aggregated data for all of the items in a group, which can aid performance analysis.

This page provides a brief overview of the API resources and methods that enable these functions.

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.

Report retrieval

The API's reports.query method lets you retrieve many different YouTube Analytics reports. Each request uses query parameters to specify a channel ID or content owner, a start date, an end date, and at least one metric. You can also provide additional query parameters, such as dimensions, filters, and sorting instructions.

Method HTTP request Description
URIs relative to https://youtubeanalytics.googleapis.com/v2
query GET /reports Retrieves a YouTube Analytics report. Each API request uses query parameters to specify a channel ID or content owner, a start date, an end date, and at least one metric. You can also provide additional query parameters, such as dimensions, filters, or sorting instructions.
  • Metrics are individual measurements of user activity, such as video views or ratings (likes and dislikes).
  • Dimensions are common criteria that are used to aggregate data, such as the date on which the user activity occurred or the country where the users were located. In a report, each row of data has a unique combination of dimension values.
  • Filters are dimension values that specify the data that will be retrieved. For example, you could retrieve data for a specific country, a specific video, or a group of videos.
The lists of supported channel reports and content owner reports define the valid combinations of metrics, dimensions, and filters.

Group management

The API provides two resources for creating and managing YouTube Analytics groups:

Groups

A group resource represents a YouTube Analytics group, which is a custom collection of up to 500 channels, videos, playlists, or assets.

All of the items in a group must represent the same type of resource. For example, you cannot create a group that contains 100 videos and 100 playlists.

An Analytics group can only contain resources that you have uploaded or claimed or that are linked to a channel that you administer. As a result, channel owners can create groups of videos and playlists. Content owners can create groups of videos, playlists, channels, or assets.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://youtubeanalytics.googleapis.com/v2
list GET /groups Returns a list of groups that match the API request parameters. For example, you can retrieve all groups that the authenticated user owns, or you can retrieve one or more groups by their unique IDs.
insert POST /groups Creates a YouTube Analytics group. After creating a group, use the groupItems.insert method to add items to the group.
update PUT /groups Modifies the metadata for a group. Currently, the only property that can be updated is the group's title. (Use the groupItems.insert and groupItems.delete to add and remove group items.)
delete DELETE /groups Deletes a group.

GroupItems

A groupItem resource represents an item in a YouTube Analytics group.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://youtubeanalytics.googleapis.com/v2
list GET /groupItems Returns a collection of group items that match the API request parameters.
insert POST /groupItems Creates a group item.
delete DELETE /groupItems Removes an item from a group.