Reports

The API supports YouTube channel owners and YouTube content owners, each of whom can access a specific set of reports:

• Channel reports contain user activity metrics for a specified channel.

• Content owner reports aggregate metrics for all of the channels linked to a specified YouTube content owner. They can include user activity metrics as well as metrics related to revenue and ad performance.

  For example, a music label's content owner report might contain combined statistics for the YouTube channels of all of the label's artists. (Content owners can also filter a report so that it only retrieves data for a specific channel.)

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

Retrieving a report

When you call the API to retrieve a report, you use the ids parameter to indicate whether you are retrieving a channel report or a content owner report. Your request also specifies the metrics that the report will include, the dimensions that will be used to aggregate data in the report, and the filters that will be used to limit the data that the API returns.

• Metrics are individual measurements of user activity, such as video views or ratings (likes and dislikes). In an API request, metrics may be requested in any order or combination. Use the required metrics request parameter to identify the desired metrics.
  
  
• 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 an API request, dimensions must be requested in the combinations listed in the channel reports and content owner reports documents. The exception to that rule is that if you specify multiple values for the same filter – filters are described below – you can also include that filter in the list of dimensions specified for the request.
  
  Use the optional dimensions request parameter to specify the dimensions to use.
  
  
• Filters are dimension values that specify the data that will be retrieved. As such, they limit the API response to only include data matching a particular value or set of values. Use the optional filters request parameter to specify filters to use.
  
  In an API request, each filter is restricted to a particular value or group of values, such as video==Zhawgd0REhA or video==pd1FJh59zxQ,Zhawgd0REhA. (Only the video, playlist, channel, and show filters support the ability to specify multiple values. The filters parameter definition explains this option in detail.)
  
  In the channel and content owner report tables, 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.

Understanding quota usage

When requesting reports, you should only request the metrics and data that your application actually needs. The API server will evaluate each query to determine how expensive it is and then deduct a variable amount from your API usage quota. While the methodology for calculating query costs is subject to change, these general guidelines will help you to optimize your quota usage:

• Additional metrics cause a request's query cost to increase.

• Additional metrics in queries that retrieve data on a per-video basis have a significantly higher cost since data is looked up for each video.

• Batch applications that fetch data and store it in their own databases should expect quota errors and implement an exponential backoff.

The following sample queries demonstrate how the first two rules might affect quota usage calculations:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.