YouTube Analytics API: Content Owner Reports

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

    This page lists reports that content owners can retrieve with the YouTube Analytics API. Content owner reports contain metrics for channels linked to a specified YouTube content owner. Metrics are individual measurements of user activity, ad performance, or estimated revenue.

    • Video reports contain user activity, ad performance, and estimated revenue metrics for videos on a content owner's channels.

    • Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist. Playlist reports use many of the same dimensions and filters as video reports.

    • 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 content owner report, call the API's reports.query method and set the ids parameter value in the API request to contentOwner== OWNER_NAME , where OWNER_NAME specifies the content owner's ID. Ask your partner manager if you are unsure of the value.

    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.

    Note:Metrics that are marked with an asterisk ( * ) require an authorization token that grants access to the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.

    Filters

    All API requests to retrieve content owner reports must filter data using either the video dimension, the channel dimension, or a supported combination of the claimedStatus and uploaderType dimensions. (Supported combinations are listed in the uploaderType dimension's definition.)

    The tables that explain the supported reports identify the filters that can be used for any given report. In the descriptions, 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.

    The API also supports the ability to specify multiple values for the video , playlist , and channel 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.

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

    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.
    Important: All API requests to retrieve content owner video reports must filter data using either the video dimension, the channel dimension, the group dimension, or a supported combination of the claimedStatus and uploaderType dimensions. (Some reports do not support all of those options.) The supported combinations, which are also listed in the uploaderType dimension's definition, are:
    • uploaderType==self
    • claimedStatus==claimed
    • claimedStatus==claimed;uploaderType==self
    • claimedStatus==claimed;uploaderType==thirdParty

    Video reports

    Basic stats

    Basic statistics (including subscriber counts)

    This report provides statistics related to user actions on all of a content owner's channels. You can filter the report to only return data for a specific video or country. It can also be used to only retrieve statistics for claimed content, including claimed content uploaded by the content owner, third parties, or both.

    Contents
    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 exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , continent , subContinent

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

    Contents
    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:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required province

    Time-based

    Activity for time periods

    This report provides statistics related to user actions on all of a content owner's channels for specific time intervals. You can filter the report to only return data for a specific video or country.

    Contents
    Dimensions:
    Use exactly 1 day , month
    Optional creatorContentType
    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 , uniques , estimatedRevenue *, estimatedAdRevenue *, grossRevenue *, estimatedRedPartnerRevenue *, monetizedPlaybacks *, playbackBasedCpm *, adImpressions *, cpm *
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , continent , subContinent

    User activity in U.S. states for specific time periods

    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.

    Contents
    Dimensions:
    Use exactly 1 day , month
    Optional creatorContentType
    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:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required province

    User geography

    User activity by country

    This report provides statistics related to user activity on a country-by-country basis for all of a content owner's channels. You can filter the report to only return data for a specific video or channel.

    Contents
    Dimensions:
    Required country
    Optional creatorContentType
    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 exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 continent , subContinent

    User activity by province

    This report provides user activity statistics for U.S. states and the District of Columbia. For this report, you must set the filters parameter value to country==US .

    Contents
    Dimensions:
    Required province
    Optional creatorContentType
    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:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required country ==US

    User activity by city (<= 250 results)

    Note:This report requires you to set the maxResults parameter to a integer value of 250 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

    This report provides user activity statistics by city.

    Contents
    Dimensions:
    Required city
    Use 0 or more creatorContentType , country , province , subscribedStatus

    Note: If you include the province dimension, you must also use the country ==US filter.
    Use 0 or 1 day , month
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageViewPercentage
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Sorting options:
    - engagedViews
    - views
    - estimatedMinutesWatched

    Playback details

    Playback detail reports provide statistics related to the following viewing attributes:

    • Was the view of a live video broadcast or an on-demand video?
    • Was the viewer subscribed to the channel that owns the video?
    • On which YouTube product did the view occur?

    Technically, the playback detail dimensions that these reports support are all optional. If you do not include playback detail dimensions in your request, the returned report will actually be similar to one of the basic stats , time-based , or user geography reports.

    Note: The liveOrOnDemand dimension and filter cannot be used in conjunction with the averageViewPercentage metric. As such, each of the following subsections lists two reports. One report supports the liveOrOnDemand dimension (and filter), while the other supports the averageViewPercentage metric.

    User activity by subscribed status

    This report provides user activity metrics for subscribed and unsubscribed viewers. Statistics can be grouped by time period ( day or month ), and the report can also be filtered by country , continent , or subContinent .

    Contents
    Dimensions:
    Use 0 or more creatorContentType , subscribedStatus
    Use 0 or 1 day , month
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , likes , dislikes , videosAddedToPlaylists , videosRemovedFromPlaylists , shares , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration , averageViewPercentage , annotationClickThroughRate , annotationCloseRate , annotationImpressions , annotationClickableImpressions , annotationClosableImpressions , annotationClicks , annotationCloses , cardClickRate , cardTeaserClickRate , cardImpressions , cardTeaserImpressions , cardClicks , cardTeaserClicks
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , continent , subContinent
    Optional subscribedStatus

    User activity by subscribed status for provinces

    This report provides user activity metrics for subscribed and unsubscribed viewers in U.S. states or the District of Columbia. This report supports fewer metrics than the previous report.

    Contents
    Dimensions:
    Use 0 or more creatorContentType , subscribedStatus
    Use 0 or 1 day , month
    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:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required province
    Optional subscribedStatus

    Playback details with optional time dimension

    The time dimension – day or month – is optional for these reports because, regardless, you need to use the startDate and endDate request parameters to specify the date range that the report will cover. The dimension, if present, indicates that you want data in the report to be aggregated by day, month, etc.

    Playback details with optional time dimension and liveOrOnDemand statistics

    This report provides playback detail statistics for specific time intervals. It supports the liveOrOnDemand dimension (and filter).

    Contents
    Dimensions:
    Use 0 or more creatorContentType , liveOrOnDemand , subscribedStatus , youtubeProduct
    Use 0 or 1 day , month
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus , youtubeProduct
    Playback details with optional time dimension and averageViewPercentage metric

    This report provides playback detail statistics for specific time intervals.

    Contents
    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 exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more subscribedStatus , youtubeProduct

    Playback details by country

    Playback details by country with liveOrOnDemand statistics

    This report provides playback detail statistics on a country-by-country basis. It supports the liveOrOnDemand dimension (and filter).

    Contents
    Dimensions:
    Optional country
    Use 0 or more creatorContentType , liveOrOnDemand , subscribedStatus , youtubeProduct
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus , youtubeProduct
    Playback details by country with averageViewPercentage metric

    The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.

    Contents
    Dimensions:
    Optional country
    Use 0 or more creatorContentType , subscribedStatus , youtubeProduct
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration , averageViewPercentage
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 continent , subContinent
    Use 0 or more subscribedStatus , youtubeProduct

    Playback details by province

    Playback details by province with liveOrOnDemand statistics

    This report provides playback detail statistics for U.S. states and the District of Columbia. It supports the liveOrOnDemand dimension (and filter).

    Contents
    Dimensions:
    Optional province
    Use 0 or more creatorContentType , liveOrOnDemand , subscribedStatus , youtubeProduct
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required country ==US
    Use 0 or more liveOrOnDemand , subscribedStatus , youtubeProduct
    Playback details by province with averageViewPercentage metric

    The following report is similar to the previous one. It adds support for the averageViewPercentage metric, but it does not support liveOrOnDemand as a dimension or a filter.

    Contents
    Dimensions:
    Optional province
    Use 0 or more creatorContentType , subscribedStatus , youtubeProduct
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration , averageViewPercentage
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required country ==US
    Use 0 or more subscribedStatus , youtubeProduct

    Playback locations

    Video playback location report

    This report provides statistics related to the type of page or application where video playbacks occurred.

    Contents
    Dimensions:
    Required insightPlaybackLocationType
    Use 0 or more creatorContentType , day , liveOrOnDemand , subscribedStatus
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus

    Playback location detail (<= 25 results)

    Note:This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

    This report identifies the embedded video players that generated the most views or viewing time for a content owner's content. When retrieving this report, you must set the insightPlaybackLocationType filter to EMBEDDED .

    Contents
    Dimensions:
    Required insightPlaybackLocationDetail
    Optional creatorContentType
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required insightPlaybackLocationType ==EMBEDDED
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus
    Sorting options:
    - engagedViews
    - views
    - estimatedMinutesWatched

    Traffic sources

    Traffic source

    This report aggregates viewing statistics based on the manner in which viewers reached your video content. For example, it identifies the number of views that stemmed from a Google search or from a link to a related video.

    Note:This report returns an error if the product of # of queried videos X # of days in date range exceeds 50,000. For example, a query that retrieves data for 500 video IDs can request data for a maximum of 100 days. To reduce the number of rows that a request returns, split your query into multiple queries that specify fewer videos or set shorter date ranges.

    Contents
    Dimensions:
    Required insightTrafficSourceType
    Use 0 or more creatorContentType , day , liveOrOnDemand , subscribedStatus
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus

    Traffic source detail (<= 25 results)

    Note:This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

    This report aggregates viewing statistics based on the referrers that generated the most views for the content owner's content. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available. For example, if you set the insightTrafficSourceType filter to ADVERTISING , the report will list the types of ads that generated the most views or viewing time for the content owner's content.

    Contents
    Dimensions:
    Required insightTrafficSourceDetail
    Optional creatorContentType
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Required insightTrafficSourceType (see note below table)
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus
    Sorting options:
    - engagedViews
    - views
    - estimatedMinutesWatched

    Note:This report is only supported for specific traffic sources. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES , and NO_LINK_EMBEDDED traffic sources are some of the unsupported ones.

    Device type and operating system

    Device type

    This report aggregates viewing statistics based on the type of device that viewers were using when watching your content. For example, it identifies the number of views that occurred on tablets or game consoles.

    Contents
    Dimensions:
    Required deviceType
    Use 0 or more creatorContentType , day , liveOrOnDemand , subscribedStatus , youtubeProduct
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more operatingSystem , liveOrOnDemand , subscribedStatus , youtubeProduct

    Operating system

    This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of views that occurred on Android devices or on PlayStations.

    Contents
    Dimensions:
    Required operatingSystem
    Use 0 or more creatorContentType , day , liveOrOnDemand , subscribedStatus , youtubeProduct
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more deviceType , liveOrOnDemand , subscribedStatus , youtubeProduct

    Operating system and device type

    This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies the number of views that occurred on Android tablets or on Windows desktop devices.

    Contents
    Dimensions:
    Required operatingSystem , deviceType
    Use 0 or more creatorContentType , day , liveOrOnDemand , subscribedStatus , youtubeProduct
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus , youtubeProduct

    Viewer demographics

    This report aggregates viewing statistics based on viewers' age group and gender.

    Contents
    Dimensions:
    Use 1 or more ageGroup , gender
    Use 0 or more creatorContentType , liveOrOnDemand , subscribedStatus
    Metrics:
    Use 1 or more
    viewerPercentage
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus
    Note: The viewerPercentage values in this report are not normalized for different values of the subscribedStatus playback detail dimension.

    For example, if a report uses the subscribedStatus dimension, then it returns viewerPercentage data adding up to 100 percent for subscribed views and viewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)

    You can use filters to ensure that the report only contains viewerPercentage data for one value of the subscribedStatus dimension.

    This report provides statistics showing how frequently the channel's videos were shared on different social platforms.

    Contents
    Dimensions:
    Required sharingService
    Optional creatorContentType , subscribedStatus
    Metrics:
    Use 1 or more
    shares
    Filters:
    Use exactly 1 video , channel , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , continent , subContinent
    Optional subscribedStatus

    Audience retention

    This report measures a video's ability to retain its audience. The elapsedVideoTimeRatio dimension measures the amount of the video that has elapsed for the corresponding metric values. The audienceWatchRatio and relativeRetentionPerformance metrics provide two measurements that show how well the video retains its audience. The first is an absolute value, while the second shows how the video performs relative to other YouTube videos of a similar length.

    Note:Audience retention reports do not support the ability to specify a comma-separated list of values for the video filter; the value must specify a single video ID.

    Contents
    Dimensions:
    Required elapsedVideoTimeRatio
    Optional creatorContentType
    Metrics:
    Use 1 or more
    audienceWatchRatio , relativeRetentionPerformance
    Filters:
    Required video
    Use 0 or more audienceType , subscribedStatus , youtubeProduct

    Top videos

    Note:These reports require you to set the maxResults parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 videos. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.

    Top videos overall, by country, by continent, or by subcontinent (<= 200 results)

    This report lists the content owner's top videos based on the specified filtering and sorting criteria.

    Contents
    Dimensions:
    Required video
    Optional creatorContentType
    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 exactly 1 channel or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , continent , subContinent
    Sorting options:
    - engagedViews
    - views
    - redViews
    - estimatedRevenue
    - estimatedRedPartnerRevenue
    - estimatedMinutesWatched
    - estimatedRedMinutesWatched
    - subscribersGained
    - subscribersLost

    Top videos overall by U.S. state (<= 200 results)

    This report lists the content owner's top videos in 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.

    Contents
    Dimensions:
    Required video
    Optional creatorContentType
    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:
    Use exactly 1 channel or a supported combination of uploaderType and claimedStatus
    Required province
    Sorting options:
    - engagedViews
    - views
    - redViews
    - estimatedMinutesWatched
    - estimatedRedMinutesWatched

    Top videos for subscribed or unsubscribed viewers (<= 200 results)

    This report lists the top videos for subscribed or unsubscribed viewers. The report can be filtered to list top videos by country , continent , or subContinent . The previous report lets you retrieve the top videos in a particular U.S. state for subscribed or unsubscribed viewers, but it supports fewer metrics than this report.

    Contents
    Dimensions:
    Required video
    Optional creatorContentType
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , likes , dislikes , videosAddedToPlaylists , videosRemovedFromPlaylists , shares , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration , averageViewPercentage , annotationClickThroughRate , annotationCloseRate , annotationImpressions , annotationClickableImpressions , annotationClosableImpressions , annotationClicks , annotationCloses , cardClickRate , cardTeaserClickRate , cardImpressions , cardTeaserImpressions , cardClicks , cardTeaserClicks
    Filters:
    Use exactly 1 channel or a supported combination of uploaderType and claimedStatus
    Optional subscribedStatus
    Use 0 or 1 country , continent , subContinent
    Sorting options:
    - engagedViews
    - views
    - redViews
    - estimatedMinutesWatched
    - estimatedRedMinutesWatched

    Top videos by YouTube Product (<= 200 results)

    This report lists top videos and supports playback detail and geographic filters. This report is similar to the previous one, but it supports fewer metrics and adds support for the youtubeProduct filter.

    Contents
    Dimensions:
    Required video
    Optional creatorContentType
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration , averageViewPercentage
    Filters:
    Use exactly 1 channel or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more subscribedStatus , youtubeProduct
    Sorting options:
    - engagedViews
    - views
    - redViews
    - estimatedMinutesWatched
    - estimatedRedMinutesWatched

    Top videos with playback detail filters (<= 200 results)

    This report lists the content owner's top videos, filtering by one or more playback detail dimensions: liveOrOnDemand , subscribedStatus , and youtubeProduct . The report also supports filtering by region.

    Contents
    Dimensions:
    Required video
    Optional creatorContentType
    Metrics:
    Use 1 or more
    engagedViews , views , redViews , estimatedMinutesWatched , estimatedRedMinutesWatched , averageViewDuration
    Filters:
    Use exactly 1 channel or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , province , continent , subContinent
    Use 0 or more liveOrOnDemand , subscribedStatus , youtubeProduct
    Sorting options:
    - engagedViews
    - views
    - redViews
    - estimatedMinutesWatched
    - estimatedRedMinutesWatched

    Playlist reports

    Playlist reports contain metrics related to user activity related to videos in the channel owner's playlists. Two versions of these reports are available, and, for each available report, the following sections contain a description of each version:

    Aggregated video metrics

    These metrics provide user activity and impression metrics that are aggregated for all videos in the playlist that are also owned by the channel that owns the playlist. Metrics for videos owned by other channels are not computed in the aggregation. As a result, if a channel creates a playlist that contains only videos owned by other channels, reports for those playlists will not provide values for these metrics.

    See the supported playlist metrics section for a list of aggregated video metrics that YouTube supports.

    In-playlist metrics

    These metrics reflect user activity and engagement in the context of the playlist page. These metrics include views for all videos in the playlist, regardless of which channel owns them, but only counts views that occurred in the playlist context.

    Supported playlist metrics

    Contents
    Aggregated video metrics
    engagedViews , views , estimatedMinutesWatched , averageViewDuration
    In-playlist metrics
    playlistViews , playlistEstimatedMinutesWatched , playlistAverageViewDuration , playlistSaves , playlistStarts , viewsPerPlaylistStart , averageTimeInPlaylist

    Basic stats

    This report provides statistics related to users' interactions with the videos in the playlists on a content owner's channels. The report does not have any required dimensions.

    Contents
    Dimensions:
    [None]
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistSaves , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    Time-based

    This report provides statistics related to users' interactions with the videos in playlists for a content owner's channels over specific time intervals. You can filter the report to only return data for a specific playlist or channel.

    Contents
    Dimensions:
    Use exactly 1
    day , month
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistSaves , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    User geography

    This report provides statistics related to interactions that users in a particular country have with the videos in the channel's playlists.

    This report provides playlist statistics by country.

    Contents
    Dimensions:
    Required
    country
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Use 0 or 1 continent , subContinent
    Optional channel

    Playlist activity by province

    This report provides playlist activity statistics for US. states and the District of Columbia. For this report, you include country==US in the filters parameter value.

    Contents
    Dimensions:
    Required
    province
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration
    Filters:
    Required country ==US
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    Playback locations

    This report provides statistics related to the type of page or application where playlist playbacks occurred.

    Contents
    Dimensions:
    Required
    insightPlaybackLocationType
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    Playback location detail (<= 25 results)

    Note:This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

    This report identifies the embedded video players that generated the most views or viewing time for a content owner's playlists.

    Contents
    Dimensions:
    Required
    insightPlaybackLocationDetail
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Required insightPlaybackLocationType ==EMBEDDED
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel
    Sorting options:
    - playlistViews
    - playlistEstimatedMinutesWatched
    - playlistStarts

    Traffic sources

    This report aggregates viewing statistics based on the manner in which viewers reached your playlist content. For example, it identifies the number of views that stemmed from a Google search or a channel page.

    Contents
    Dimensions:
    Required
    insightTrafficSourceType
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistSaves , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    Traffic source detail (<= 25 results)

    Note:This report requires you to set the maxResults parameter to a integer value of 25 or less. Unlike most other reports, this report also requires you to specify a value for the sort request parameter.

    This report aggregates viewing statistics based on the referrers that generated the most views for the content owner's playlists. Referrers are categorized by traffic source type, and the insightTrafficSourceDetail dimension's definition identifies the traffic sources for which the report is available. For example, if you set the insightTrafficSourceType filter to ADVERTISING , the report will list the types of ads that generated the most views or viewing time for the content owner's playlists.

    Contents
    Dimensions:
    Required
    insightTrafficSourceDetail
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistSaves , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Required insightTrafficSourceType
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel
    Sorting options:
    - playlistViews
    - playlistEstimatedMinutesWatched
    - playlistStarts

    Note:This report is only supported for specific traffic sources. VIDEO_REMIXES , NOTIFICATION , END_SCREEN , CAMPAIGN_CARD , VIDEO_REMIXES , and NO_LINK_EMBEDDED traffic sources are some of the unsupported ones.

    Device type and operating system

    Device type for playlists

    This report aggregates viewing statistics based on the device type that viewers used to watch your playlist content. For example, it identifies the number of views that occurred on mobile devices or game consoles.

    Contents
    Dimensions:
    Required
    deviceType
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    Operating system for playlists

    This report aggregates viewing statistics based on viewers' operating systems. For example, it identifies the number of playlist views that occurred on Android devices or on PlayStations.

    Contents
    Dimensions:
    Required
    operatingSystem
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    Operating system and device type for playlists

    This report aggregates viewing statistics based on viewers' operating systems and device types. For example, it identifies the number of playlist views that occurred on Android tablets or on Windows desktop devices.

    Contents
    Dimensions:
    Required
    deviceType , operatingSystem
    Metrics:
    Use 1 or more
    engagedViews , views , estimatedMinutesWatched , averageViewDuration , averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistStarts , playlistViews , viewsPerPlaylistStart
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel

    Viewer demographics

    This report aggregates viewing statistics based on viewers' age group and gender.

    Contents
    Dimensions:
    Use 1 or more
    ageGroup , gender
    Metrics:
    Required
    viewerPercentage
    Filters:
    Use 0 or 1 * playlist , group

    Note: Exactly one of these filters must be specified if any of the views , estimatedMinutesWatched , or averageViewDuration metrics is requested in the report.
    Optional channel
    Note: The viewerPercentage values in this report are not normalized for different values or combinations of values for playback detail dimensions ( subscribedStatus and youtubeProduct ).

    For example, a report that uses the subscribedStatus dimension returns viewerPercentage data adding up to 100 percent for subscribed views and viewerPercentage data adding up to 100 percent for unsubscribed views. (The total value of all viewerPercentage fields in the report is 200 percent.)

    You can use filters to ensure that the report only contains viewerPercentage data for one value (or combination of values) for playback detail dimensions.

    Top playlists

    Note:These reports require you to set the maxResults parameter to an integer value of 200 or less. Before January 1, 2013 data is only available for the top 10 playlists. Unlike most other reports, these reports also require you to specify a value for the sort request parameter.

    This report lists the content owner's top playlists based on the specified filtering and sorting criteria.

    Contents
    Dimensions:
    Required
    playlist
    Metrics:
    Use 1 or more
    averageTimeInPlaylist , playlistAverageViewDuration , playlistEstimatedMinutesWatched , playlistSaves , playlistStarts , playlistViews , viewsPerPlaylistStart
    Sorting options:
    - playlistViews
    - playlistEstimatedMinutesWatched
    - playlistStarts

    Ad performance reports

    Note:Ad performance reports require an authorization token that grants access to the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope.

    Ad performance reports provide impression-based metrics for ads that ran during video playbacks. These metrics account for each ad impression, and each video playback can yield multiple impressions.

    The impression-based ad performance metrics are:

    In addition, some video reports support the following playback-based ad performance metrics. However, these metrics are not included in ad performance reports.

    Ad performance by ad type

    Contents
    Dimensions:
    Required adType
    Optional day
    Metrics:
    Use 1 or more
    grossRevenue , adImpressions , cpm
    Filters:
    Use exactly 1 video , group , or a supported combination of uploaderType and claimedStatus
    Use 0 or 1 country , continent , subContinent
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: