API Reference

    • The YouTube Analytics API allows retrieval of YouTube Analytics data for channels or content owners, supporting real-time queries to generate reports.

    • The API offers report retrieval via the reports.query method, allowing specification of metrics, dimensions, filters, and sorting instructions, all defined by request parameters.

    • YouTube Analytics groups are customizable collections of up to 500 channels, videos, playlists, or assets, which help in aggregating data for performance analysis and are manageable through the API.

    • Authorization for API requests requires OAuth 2.0 and uses specific scopes, such as yt-analytics.readonly for viewing user activity metrics and yt-analytics-monetary.readonly for viewing financial reports.

    • The API provides methods to manage YouTube Analytics groups including creating, listing, updating, and deleting groups and their items, with channels, videos, playlists, and assets being the acceptable components.

    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.
    • Metricsare individual measurements of user activity, such as video views or ratings (likes and dislikes).
    • Dimensionsare 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.
    • Filtersare 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.
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: