Reports: Query

Important: API requests to this method now require access to the https://www.googleapis.com/auth/youtube.readonly scope.

This method lets you retrieve many different 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.

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

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

Common use cases

Request

HTTP request

GET https://youtubeanalytics.googleapis.com/v2/reports

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.

Parameters

The following tables list required and optional query parameters for API requests to retrieve query reports. The standard query parameters listed in the table are also optional and are supported by many Google APIs.

Parameter Description
Required Parameters
endDate string
The end date for fetching YouTube Analytics data. The value should be in YYYY-MM-DD format.

The API response contains data up until the last day for which all metrics in the query are available at the time of the query. So, for example, if the request specifies an end date of July 5, 2017, and values for all of the requested metrics are only available through July 3, 2017, that will be the last date for which data is included in the response. (That is true even if data for some of the requested metrics is available for July 4, 2017.)
Note: In version 1 of the API, this parameter was named end-date.
ids string
Identifies the YouTube channel or content owner for which you are retrieving YouTube Analytics data.

  • To request data for a YouTube channel, set the ids parameter value to either channel==MINE or channel==CHANNEL_ID, where CHANNEL_ID identifies the currently authenticated user's YouTube channel.
  • To request data for a YouTube content owner, set the ids parameter value to contentOwner==OWNER_NAME, where OWNER_NAME is the content owner ID for the user.

metrics string
A comma-separated list of YouTube Analytics metrics, such as views or likes,dislikes. See the documentation for channel reports or content owner reports for a list of the reports that you can retrieve and the metrics available in each report. (The Metrics document contains definitions for all of the metrics.)
startDate string
The start date for fetching YouTube Analytics data. The value should be in YYYY-MM-DD format.
Note: In version 1 of the API, this parameter was named start-date.
Optional Parameters
currency string
The currency that the API will use to specify the following estimated revenue metrics: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. The values that the API returns for those metrics are estimates calculated using exchange rates that change on a daily basis. If none of those metrics are requested, the parameter is ignored.

The parameter value is a three-letter ISO 4217 currency code from the list of currencies below. The API returns an error if an unsupported currency is specified. The default value is USD.
dimensions string
A comma-separated list of YouTube Analytics dimensions, such as video or ageGroup,gender. See the documentation for channel reports or content owner reports for a list of the reports that you can retrieve and the dimensions used for those reports. (The Dimensions document contains definitions for all of the dimensions.)
filters string
A list of filters that should be applied when retrieving YouTube Analytics data. The documentation for channel reports and content owner reports identifies the dimensions that can be used to filter each report, and the Dimensions document defines those dimensions.

If a request uses multiple filters, join them together with a semicolon (;), and the returned result table will satisfy both filters. For example, a filters parameter value of video==dMH0bHeiRNg;country==IT restricts the result set to include data for the given video in Italy.

Specifying multiple values for a filter

The API supports the ability to specify multiple values for the video, playlist, and channel filters. To do so, specify a separated list of the video, playlist, or channel IDs for which the API response should be filtered. For example, a filters parameter value of video==pd1FJh59zxQ,Zhawgd0REhA;country==IT restricts the result set to include data for the given videos in Italy. The parameter value can specify up to 500 IDs. Note: Audience Retention reports (dimensions=elapsedVideoTimeRatio) only support filtering by a single video ID.

When specifying multiple values for the same filter, 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. If you do add the filter to the list of dimensions, then the API also uses the filter values to group results.

For example, suppose you retrieve a channel's traffic source report, which aggregates viewing statistics based on the manner in which viewers reached the channel's video content. Also suppose that your request's filters parameter request identifies a list of 10 videos for which data should be returned.
  • If you add video to the dimensions parameter's value, the API response will provide separate traffic source statistics for each of the 10 videos.
  • If you do not add video to the dimensions parameter's value, the API response will aggregate the traffic source statistics for all of the 10 videos.
includeHistoricalChannelData boolean
Note: This parameter only applies to content owner reports.

Indicates whether the API response should include channels' watch time and view data from the time period prior to when the channels were linked to the content owner. The default parameter value is false which means that the API response only includes watch time and view data from the dates that channels were linked to the content owner.

It is important to remember that different channels might have been linked to a content owner on different dates. If the API request is retrieving data for multiple channels and the parameter value is false, then the API response contains data based on the linking date for each respective channel. If the parameter value is true, the API response contains data matching the dates specified in the API request.
Note: In version 1 of the API, this parameter was named include-historical-channel-data.
maxResults integer
The maximum number of rows to include in the response.
Note: In version 1 of the API, this parameter was named max-results.
sort string
A comma-separated list of dimensions or metrics that determine the sort order for YouTube Analytics data. By default the sort order is ascending. The - prefix causes descending sort order.
startIndex integer
The 1-based index of the first entity to retrieve. (The default value is 1.) Use this parameter as a pagination mechanism along with the max-results parameter.
Note: In version 1 of the API, this parameter was named start-index.
Standard Parameters