關於 youtube view count statistics ，我們在網路上蒐集到這些相關的討論、資訊與評價

This page lists reports that channel owners can retrieve with the YouTube Analytics API. Channel reports provide user activity metrics for a specified channel and measure things like video views, ratings, and subscription counts.

Video reports provide statistics for all user activity related to a channel's videos.
Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist.

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 channel report, you must set the ids parameter value in your API request to one of the following values:

channel==MINE – The API returns data for the authenticated user's YouTube channel.

channel==CHANNEL_ID – Set CHANNEL_ID to the unique channel ID of the channel for which you are retrieving data. The user authorizing the request must be the owner of the channel.

The channel ID is currently a string that begins with the letters UC, though its format is subject to change. (You can find your channel's ID on the advanced account settings page for your YouTube channel, or you can retrieve your channel's ID programmatically using the YouTube Data API's channels.list method.)

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: Estimated revenue and ad performance metrics are not currently supported for channel reports. As a result, the https://www.googleapis.com/auth/yt-analytics-monetary.readonly scope does not currently grant access to monetary data in those reports.

Filters

The tables that explain the supported reports identify the filters that can be used for each report. In the tables, filters shown in parentheses are optional. For example, for the filtering option video(,country), the video filter is required, and the country filter is optional.

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


Video reports
Basic stats
Basic user activity statistics

This report provides statistics related to users' actions on a channel. You can filter the report to only return data for a specific video or country.

Contents

Dimensions:




[None]










Metrics:



Use 1 or more
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 0 or 1
country, continent, subContinent




Use 0 or 1
video, group







Basic user activity 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
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks




Filters:




Required
province




Use 0 or 1
video, group







Time-based
User activity by country for specific time periods

This report provides statistics related to user actions on a channel 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
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 0 or 1
country, continent, subContinent




Use 0 or 1
video, group







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

This report provides statistics related to user activity 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
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks




Filters:




Required
province




Use 0 or 1
video, group







User geography
User activity by country

This report provides statistics related to user activity on a country-by-country basis for a channel. You can filter the report to only return data for a specific video.

Contents

Dimensions:




Required
country




Optional
creatorContentType








Metrics:



Use 1 or more
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 0 or 1
continent, subContinent




Use 0 or 1
video, group







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
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks




Filters:




Required
country==US




Use 0 or 1
video, group







User activity by city (<= 250 results)

Note: This report requires you to set the maxResults
parameter to an 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
views, estimatedMinutesWatched, averageViewDuration, averageViewPercentage




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group








Sorting options:
-views
-estimatedMinutesWatched
User activity by DMA

This report provides user activity statistics by Designated Market Area (DMA). For this report,
you must either set the filters parameter value to country==US or
filter to a particular province (U.S. state).

Contents

Dimensions:




Required
dma




Use 0 or 1
day
month
creatorContentType
subscribedStatus








Metrics:



Use 1 or more
views
estimatedMinutesWatched
averageViewDuration
averageViewPercentage




Filters:




Use 0 or 1
country==US
province




Use 0 or 1
video
group








Sorting options:
-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?

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
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 0 or 1
country, continent, subContinent




Use 0 or 1
video, group




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
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks




Filters:




Use 0 or 1
video, group




Use 0 or more
province, 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
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




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. It supports the averageViewPercentage metric.

Contents

Dimensions:




Use 0 or more
creatorContentType, subscribedStatus, youtubeProduct




Use 0 or 1
day, month








Metrics:



Use 1 or more
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






Playback details by countryPlayback 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:




Required
country




Use 0 or more
creatorContentType, liveOrOnDemand, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration




Filters:




Use 0 or 1
continent, subContinent




Use 0 or 1
video, group




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:




Required
country




Use 0 or more
creatorContentType, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage




Filters:




Use 0 or 1
continent, subContinent




Use 0 or 1
video, group




Use 0 or more
subscribedStatus, youtubeProduct






Playback details by provincePlayback 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:




Required
province




Use 0 or more
creatorContentType, liveOrOnDemand, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration




Filters:




Required
country==US




Use 0 or 1
video, group




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:




Required
province




Use 0 or more
creatorContentType, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage




Filters:




Required
country==US




Use 0 or 1
video, group




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
views, estimatedMinutesWatched




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




Use 0 or more
liveOrOnDemand, subscribedStatus






Playback location detail (<= 25 results)

Note: This report requires you to set the maxResults parameter to an 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 channel's videos.

Contents

Dimensions:




Required
insightPlaybackLocationDetail




Optional
creatorContentType








Metrics:



Use 1 or more
views, estimatedMinutesWatched




Filters:




Required
insightPlaybackLocationType==EMBEDDED




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




Use 0 or more
liveOrOnDemand, subscribedStatus






Sorting options:
-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
views, estimatedMinutesWatched




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




Use 0 or more
liveOrOnDemand, subscribedStatus






Traffic source detail (<= 25 results)

Note: This report requires you to set the maxResults parameter to an 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 channel'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 channel's content.

Contents

Dimensions:




Required
insightTrafficSourceDetail




Optional
creatorContentType








Metrics:



Use 1 or more
views, estimatedMinutesWatched




Filters:




Required
insightTrafficSourceType (see note below table)




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




Use 0 or more
liveOrOnDemand, subscribedStatus






Sorting options:
-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 manner in which viewers reached your video content. For example, it identifies the number of views that occurred on mobile devices or game consoles.

Contents

Dimensions:




Required
deviceType




Use 0 or more
creatorContentType, day, liveOrOnDemand, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, estimatedMinutesWatched




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




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
views, estimatedMinutesWatched




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




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
deviceType, operatingSystem




Use 0 or more
creatorContentType, day, liveOrOnDemand, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, estimatedMinutesWatched




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




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 0 or 1
country, province, continent, subContinent




Use 0 or 1
video, group




Use 0 or more
liveOrOnDemand, subscribedStatus








Engagement and content sharing

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

Contents

Dimensions:




Required
sharingService




Use 0 or more
creatorContentType, subscribedStatus








Metrics:



Use 1 or more
shares




Filters:




Use 0 or 1
country, continent, subContinent




Use 0 or 1
video, group




Optional
subscribedStatus






Audience retention

This report measures a video's ability to retain its audience and also shows how often specific
parts of a video were watched. The elapsedVideoTimeRatio dimension measures
the amount of the video that has elapsed for the corresponding metric values. The metrics can
be broken down into two categories:

Audience retention

These metrics show how well the video retains its audience.

audienceWatchRatio is a ratio that compares the number of times a
portion of a video has been watched to the total number of views of the video.
relativeRetentionPerformance shows how well a video retains viewers
during playbacks relative to other YouTube videos of a similar length.

Granular watch statistics

These metrics provide information about how often specific parts of a video were watched.

startedWatching indicates how often viewers started watching a video
during a particular segment of the video.
stoppedWatching indicates how often viewers stopped watching a video
during a particular segment of the video.
totalSegmentImpressions indicates how often a particular sgement of the
video was viewed.

Note: This report does 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









Metrics:



Use 1 or more
audienceWatchRatio
relativeRetentionPerformance
startedWatching
stoppedWatching
totalSegmentImpressions




Filters:




Required
video




Use 0 or more
audienceType
subscribedStatus
youtubeProduct







Concurrent viewers (for livestreams)

This report shows the concurrent viewers at a given position for a single live-streamed video.
The filter specifies the video. The position dimension generally represents a single minute.

Contents

Dimensions:




Use 0 or 1
livestreamPosition









Metrics:



Use 1 or more
averageConcurrentViewers
peakConcurrentViewers




Filters:




Required
video








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 with optional regional filters (<= 200 results)

This report lists the channel's top videos. The report can be filtered to list top videos by country, continent, or subContinent.

Contents

Dimensions:




Required
video




Optional
creatorContentType








Metrics:



Use 1 or more
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 0 or 1
country, continent, subContinent









Sorting options:
-views
-redViews
-estimatedRevenue
-estimatedRedPartnerRevenue
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-subscribersGained
-subscribersLost
Top videos by state (<= 200 results)

This report lists the channel'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
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks




Filters:




Required
province




Optional
subscribedStatus








Sorting options:
-views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
Top videos for subscribed or unsubscribed viewers(<= 200 results)

This report lists the channel's 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
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:




Optional
subscribedStatus




Use 0 or 1
country, continent, subContinent








Sorting options:
-views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
Top videos by YouTube Product (<= 200 results)

This report lists the channel's 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
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
subscribedStatus, youtubeProduct








Sorting options:
-views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
Top videos with playback detail filters (<= 200 results)

This report lists the channel's top videos, filtering by any or all of the playback detail dimensions: liveOrOnDemand, subscribedStatus, and youtubeProduct. Unlike the previous report, this one supports the liveOrOnDemand filter and does not support the averageViewPercentage metric.

Contents

Dimensions:




Required
video




Optional
creatorContentType








Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration




Filters:




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
liveOrOnDemand, subscribedStatus, youtubeProduct








Sorting options:
-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:

The Recommended tab in each section describes the preferred API request format for
retrieving the corresponding report. The recommended reports support an expanded set of metrics
that includes both aggregated video metrics and
in-playlist metrics. This request format does not use the
isCurated dimension.
The Using isCurated tab in each section describes an older API request
format in which the isCurated dimension is required. These reports support
in-playlist metrics only. Note that the
isCurated dimension has been deprecated for all reports. The warning note below
explains the deprecation schedule.

The following warning note explains changes between the two report versions in more detail.

Important: Update playlist reports for channels before June 30, 2024, and update playlist
reports for content owners by December 31, 2024. Please note the following changes:

The isCurated
dimension has been deprecated.

For channel reports, this dimension will no longer be supported on or after
June 30, 2024.
For content owner reports, this dimension will no longer be supported on or after
December 31, 2024.


The behavior of the views metric changes
when you remove the isCurated dimension from a request to retrieve a playlist
report:

When a request includes the isCurated dimension, the
views metric indicates the
number of times that the video was viewed in the context of the playlist.
When a request does not include the isCurated dimension, the
views metric specifies the total number of times that the video was viewed,
while the playlistViews metric indicates the number of times that the video
was viewed in the context of the playlist.


As a result, to preserve backward compatibility when you remove the isCurated
dimension, you must also update your code to retrieve the playlistViews metric
instead of the views metric for playlist reports only. Since the views
metric is still supported for playlist reports, albeit with a different meaning, the API will
still return data if you do not update the metric name. Of course, you can modify your application
to retrieve and display both views and playlistViews.

See the revision history for more details.
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 metricsImportant: As shown in the tables below, the
views metric provides different types
of data in the two available versions of each playlist report.
In the recommended report format, views is an aggregated video metric.
In reports retrieved using the isCurated dimension, views is an
in-playlist metric.



Recommended

Contents


Aggregated video metrics
views, estimatedMinutesWatched, averageViewDuration


in-playlist metrics
playlistViews, playlistEstimatedMinutesWatched, playlistAverageViewDuration,
playlistSaves, playlistStarts,
viewsPerPlaylistStart, averageTimeInPlaylist




Using isCurated

Contents


Aggregated video metrics
Not supported


in-playlist metrics
views, estimatedMinutesWatched, averageViewDuration,
averageViewPercentage, redViews, estimatedRedMinutesWatched




Basic stats

This report provides statistics related to users' interactions with the videos in the channel's
playlists. You can filter the report to only return data for a specific playlist.

Recommended





Contents

Dimensions:




[None]










Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistSaves, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:





Use exactly 1
playlist, group










Using isCurated

The isCurated dimension has
been deprecated and will no longer be supported for channel reports on or after June 30, 2024. The
Playlist reports migration guide
explains other changes you can or need to make in association with this deprecation.








Contents

Dimensions:




[None]










Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
subscribedStatus, youtubeProduct







Time-based

This report provides statistics related to users' interactions with the videos in the channel's
playlists. You can filter the report to only return data for a specific playlist.

Recommended




Contents

Dimensions:




Use exactly 1
day, month









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistSaves, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:





Use exactly 1
playlist, group










Using isCurated










Contents

Dimensions:




Use exactly 1
day, month




Use 0 or more
subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
subscribedStatus, youtubeProduct








User geography
Playlist activity by country

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

Recommended



Contents

Dimensions:




Required
country









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration




Filters:





Use exactly 1
playlist, group




Use 0 or 1
continent, subContinent









Using isCurated









Contents

Dimensions:




Required
country




Use 0 or more
subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
continent, subContinent




Use 0 or more
subscribedStatus, youtubeProduct








Playlist activity by province

This report provides playlist activity statistics for U.S. states and the District of Columbia.
For this report, you must filter results to return data only for the United States.

Recommended



Contents

Dimensions:




Required
province









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration




Filters:




Required
country==US




Use exactly 1
playlist, group










Using isCurated





Contents

Dimensions:




Required
province









Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1;country==US




Use 0 or 1
playlist, group




Use 0 or more
subscribedStatus, youtubeProduct









Playback locations

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

Recommended




Contents

Dimensions:




Required
insightPlaybackLocationType









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:





Use exactly 1
playlist, group










Using isCurated









Contents

Dimensions:




Required
insightPlaybackLocationType




Use 0 or more
day, subscribedStatus








Metrics:



Use 1 or more
views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Optional
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 the videos in the channel's playlists.

Recommended




Contents

Dimensions:




Required
insightPlaybackLocationDetail









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:




Required
insightPlaybackLocationType==EMBEDDED




Use exactly 1
playlist, group








Sorting options:
-playlistViews
-playlistEstimatedMinutesWatched
-playlistStarts



Using isCurated








Contents

Dimensions:




Required
insightPlaybackLocationDetail









Metrics:



Use 1 or more
views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1;insightPlaybackLocationType==EMBEDDED




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Optional
subscribedStatus






Sorting options:
-views
-estimatedMinutesWatched
-playlistStarts


Traffic sources

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

Recommended




Contents

Dimensions:




Required
insightTrafficSourceType









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistSaves, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:





Use exactly 1
playlist, group










Using isCurated










Contents

Dimensions:




Required
insightTrafficSourceType




Use 0 or more
day, subscribedStatus








Metrics:



Use 1 or more
views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Optional
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 videos in the channel'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 channel's playlists.

Recommended





Contents

Dimensions:




Required
insightTrafficSourceDetail









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistSaves, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:




Required
insightTrafficSourceType==ADVERTISING (or another supported value)




Use exactly 1
playlist, group








Sorting options:
-playlistViews
-playlistEstimatedMinutesWatched
-playlistStarts



Using isCurated








Contents

Dimensions:




Required
insightTrafficSourceDetail









Metrics:



Use 1 or more
views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1;insightTrafficSourceType==ADVERTISING (or another supported value)




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Optional
subscribedStatus






Sorting options:
-views
-estimatedMinutesWatched
-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

This report aggregates viewing statistics based on how viewers reached the videos in your
playlists. For example, it identifies the number of views that occurred on mobile devices or game
consoles.

Recommended




Contents

Dimensions:




Required
deviceType









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:





Use exactly 1
playlist, group










Using isCurated









Contents

Dimensions:




Required
deviceType




Use 0 or more
day, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
operatingSystem, 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.

Recommended




Contents

Dimensions:




Required
operatingSystem









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:





Use exactly 1
playlist, group










Using isCurated









Contents

Dimensions:




Required
operatingSystem




Use 0 or more
day, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
deviceType, subscribedStatus, youtubeProduct








Operating system and device type

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

Recommended




Contents

Dimensions:




Required
deviceType, operatingSystem









Metrics:



Use 1 or more
views, estimatedMinutesWatched, averageViewDuration, averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistStarts, playlistViews, viewsPerPlaylistStart




Filters:





Use exactly 1
playlist, group










Using isCurated









Contents

Dimensions:




Required
deviceType, operatingSystem




Use 0 or more
day, subscribedStatus, youtubeProduct








Metrics:



Use 1 or more
views, estimatedMinutesWatched, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
subscribedStatus, youtubeProduct








Viewer demographics

Recommended


Contents

Dimensions:




Use 1 or more
ageGroup, gender









Metrics:



Required
viewerPercentage




Filters:





Use exactly 1
playlist, group










Using isCurated









Contents

Dimensions:




Use 1 or more
ageGroup, gender




Use 0 or more
subscribedStatus








Metrics:



Required
viewerPercentage




Filters:




Required
isCurated==1




Use 0 or 1
playlist, group




Use 0 or 1
country, province, continent, subContinent




Optional
subscribedStatus








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 channel's top playlists based on the specified filtering and sorting criteria.

Recommended



Contents

Dimensions:




Required
playlist









Metrics:



Use 1 or more
averageTimeInPlaylist, playlistAverageViewDuration, playlistEstimatedMinutesWatched, playlistSaves, playlistStarts, playlistViews, viewsPerPlaylistStart





Sorting options:
-playlistViews
-playlistEstimatedMinutesWatched
-playlistStarts



Using isCurated









Contents

Dimensions:




Required
playlist









Metrics:



Use 1 or more
views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, playlistStarts, viewsPerPlaylistStart, averageTimeInPlaylist




Filters:




Required
isCurated==1




Use 0 or 1
country, province, continent, subContinent




Use 0 or more
playlist, subscribedStatus, youtubeProduct







Sorting options:
-views
-redViews
-estimatedMinutesWatched
-estimatedRedMinutesWatched
-playlistStarts


Membership reports
Membership cancellations

This report provides statistics showing why users canceled their channel memberships.

Contents

Dimensions:




Use 0 or 1
membershipsCancellationSurveyReason









Metrics:



Required
membershipsCancellationSurveyResponses




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:

grossRevenue
adImpressions
cpm

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

playbackBasedCpm
monetizedPlaybacks

Ad performance by ad type


Contents

Dimensions:




Required
adType




Optional
day








Metrics:



Use 1 or more
grossRevenue, adImpressions, cpm




Filters:




Use 0 or 1
video, group




Use 0 or 1
country, continent, subContinent