Dimensions

This document defines the dimensions that the YouTube Analytics API supports. This API supports real-time, targeted queries to generate custom YouTube Analytics reports.

Dimensions are common criteria that are used to aggregate data, such as the date on which user activity occurred or the country where users were located.

Each query report identifies the dimensions that it supports. For example, when retrieving user activity by time, you choose the time period for which data will be reported: day or month. In any report, each row of data has a unique combination of dimension values.

To retrieve a query report, call the YouTube Analytics API's reports.query method. In your request, use the dimensions parameter to specify the dimensions that YouTube will use to calculate metric values in the reports.

Core dimensions

While the YouTube Analytics API is subject to the Deprecation Policy defined in the Terms of Service, non-core dimensions (and non-core metrics) are not subject to the policy. In the definitions on this page, any dimension that is a core dimension is explicitly identified as such.

The following list identifies the API's core dimensions.

For more information, see the list of the YouTube APIs subject to the Deprecation Policy.

Filters

All query reports support filters. Filters identify dimension values that must be present in the retrieved dataset. As such, they limit an API response to only include data matching a particular value or set of values. For example, instead of retrieving user activity metrics for all countries, you could use a filter to only retrieve data for a particular country.

In a request to retrieve a query report, the optional filters request parameter specifies the dimension values for which you want to filter data. For example, to retrieve user activity metrics for Europe, you would set the filters parameter value to continent==150.

Important: API requests to retrieve content owner reports must filter data by either using one of the reporting entity dimensions or using a supported combination of the claimedStatus and uploaderType dimensions.

Dimensions

The following sections define the dimensions that are used in the YouTube Analytics API's query reports. Unless otherwise noted, these dimensions are used in both channel and content owner reports. Dimensions that can only be used as filters are also identified.

Resources

These dimensions correspond to resources that channels and content owners manage on YouTube:

Note: The API lets you specify multiple values for the video, playlist, and channel dimensions when they are used as filters. To do so, set the filters parameter value to a comma-separated list of the video, playlist, or channel IDs for which the API response should be filtered. The parameter value can specify up to 500 IDs.

video (core dimension)
The ID of a YouTube video. In the YouTube Data API, this is the value of a video resource's id property. This is a core dimension and is subject to the Deprecation Policy.
playlist
The ID of a YouTube playlist. In the YouTube Data API, this is the value of a playlist resource's id property.
channel (core dimension) (only used in content owner reports)
The ID for a YouTube channel. In the YouTube Data API, this is the value of a channel resource's id property. This is a core dimension and is subject to the Deprecation Policy.

The channel dimension is frequently used in content owner reports because those reports typically aggregate data for multiple channels.
group (filter only)
The ID of a YouTube Analytics group. You can retrieve this value using the YouTube Analytics API's groups.list method. When you use the group filter, the API response contains data for all of the videos, playlists, or channels in that group.

Examples

The following sample requests use reporting entity dimensions or filters:

  • Channel examples

    • Basic stats
      • Top 10 – Most watched videos for a channel
      • Top 10 – Annotation click-through rates for a channel's most viewed videos
      • Statistics for a specific playlist
      • Top 10 – Most watched playlists for a channel
    • Geographic
      • Top 10 – Most viewed videos in a specific country
      • Top 10 – Most viewed videos in Europe

  • Content owner examples

    • Basic stats
      • Top 10 - Most viewed videos for a content owner
      • Top 10 - Most watched videos for a content owner
      • Top 10 - Most viewed videos for a content owner's channel
      • Top 10 – Annotation click-through rates for a channel's most viewed videos
      • Top 10 – Most watched playlists for a content owner
    • Geographic
      • Top 10 - Most watched videos in Europe for a content owner
      • Top 10 – Most started playlists in the United States

Geographic areas

These dimensions identify a geographic region associated with user activity, ad performance, or estimated revenue metrics.

country (core dimension)
The country associated with the metrics in the report row. The dimension value is a two-letter ISO-3166-1 country code, such as US, CN (China), or FR (France). The country code ZZ is used to report metrics for which YouTube could not identify the associated country. This is a core dimension and is subject to the Deprecation Policy.
province
The U.S. state or territory associated with the metrics in the report row. The dimension value is an ISO 3166-2 code that identifies a U.S. state or the District of Columbia, such as US-MI (Michigan) or US-TX (Texas). The province code US-ZZ is used to report metrics for which YouTube could not identify the associated U.S. state. When an API request includes province in the dimensions parameter value, the request must also restrict data to the United States by including country==US in the filters parameter value.

Note: This dimension does not support ISO 3166-2 values that identify U.S. outlying areas since those territories also have their own ISO 3166-1 country codes. It also does not support subdivisions of countries other than the United States.

dma
The 3-digit identifier that Nielsen uses to identify the Designated Market Area (DMA) associated with the viewing events described in the data row.
city
The estimated city associated with the metrics in the report row. Data for this dimension is available for dates beginning January 1, 2022.
continent (filter only)
A United Nations (UN) statistical region code. The API supports the following values:
Values
002 Africa
019 Americas (Northern America, Latin America, South America, and the Caribbean)
142 Asia
150 Europe
009 Oceania
This dimension can only be used to filter data. To use this dimension, set the value of the filters parameter to continent==REGION_CODE, specifying a REGION_CODE value from the table.
subContinent (filter only)
A UN statistical region code that identifies a geographical sub-region. The United Nations Statistics Division lists sub-regions as well as the countries it associates with each region.

This dimension can only be used to filter data. To use this dimension, set the value of the filters parameter to subContinent==REGION_CODE, specifying a REGION_CODE value from the UN list.

Examples

The following sample requests use geographic dimensions or filters:

  • Channel examples

    • Basic stats: Country-specific view counts (and more) for a channel
    • Geographic
      • Country-specific watch time metrics for a channel's videos
      • Country-specific annotation metrics for a channel's videos
      • Province-specific metrics for U.S. states and Washington D.C.
      • Country-specific watch time metrics for a channel's playlists
      • Top 10 – Most started playlists in the United States
    • Playback location: Daily view counts and watch time from different playback locations
    • Traffic source: Viewcounts and watch time from different traffic sources in a country
    • Demographic: Viewer demographics in California (age group and gender)
    • Top videos
      • Top 10 – Most viewed videos in a specific country
      • Top 10 – Most viewed videos in Europe

  • Content owner examples

    • Basic stats: Country-specific view counts (and more) for all self-uploaded videos
    • Geographic
      • Country-specific watch time metrics for self-uploaded content
      • Country-specific annotation metrics for self-uploaded content
      • Province-specific metrics for U.S. states and Washington D.C.
      • Country-specific watch time metrics for a content owner's playlists
      • Top 10 – Most started playlists in the United States
    • Playback location: Daily view counts and watch time from different playback locations
    • Demographic: Viewer demographics in California (age group and gender)
    • Top videos: Top 10 – Most watched videos in Europe for a content owner
    • Revenue/Ad performance: Country-specific revenue and ad performance metrics

Time periods

These dimensions indicate that a report should aggregate data based on a time period, such as a day, a week, or a month. The startDate and endDate request parameters specify the time period for which the report includes data. Note that the report actually returns data up until the last day for which all metrics specified in the request are available at the time the query is made. In reports, dates are listed in YYYY-MM-DD format.

Important: All dates refer to the time period beginning at 12:00AM Pacific time (UTC-7 or UTC-8) and ending at 11:59PM Pacific time on the specified day, month, and year. As a result, dates when clocks are adjusted forward for Daylight Savings Time represent a 23-hour period, and dates when clocks are adjusted backward represent a 25-hour period.

The month dimension refers to the time period beginning at 12:00AM Pacific time (UTC-7 or UTC-8) on the first day of the specified month and year.

day (core dimension)
When you use this dimension, data in the report is aggregated on a daily basis and each row contains data for one day. You can use other dimensions to break down the data even further. For example, a traffic source report can aggregate daily viewing statistics based on the manner in which users reach your videos. This is a core dimension and is subject to the Deprecation Policy.
month (core dimension)
Data in the report is aggregated by calendar month. As with daily reports, you can use other filters to segment the data even further. In the report, dates are listed in YYYY-MM format.

Note: If your API query uses the month dimension, then the start-date and end-date parameters must both be set to the first day of the month. This is a core dimension and is subject to the Deprecation Policy.

Examples

The following sample requests use temporal dimensions or filters:

  • Channel examples

    • Time-based
      • Daily watch time metrics for a channel's videos
      • Daily annotation metrics for a channel's videos
      • Daily playlist views for a channel
    • Playback location: Daily view counts and watch time from different playback locations
    • Traffic source: Daily view counts and watch time from different traffic sources
    • Device/OS
      • Daily device type metrics for the Android operating system
      • Daily operating system metrics for mobile devices
      • Daily operating system and device type metrics

  • Content owner examples

    • Time-based
      • Daily watch time metrics for self-uploaded content
      • Annotation metrics for claimed content
      • Daily playlist views for a content owner
    • Playback location: Daily view counts and watch time from different playback locations
    • Traffic source: Daily view counts and watch time from different traffic sources
    • Device/OS
      • Daily device type metrics for claimed videos
      • Daily operating system metrics for claimed videos viewed on mobile devices
      • Daily operating system and device type metrics
    • Revenue/Ad performance: Daily revenue and ad performance metrics

Playback locations

These dimensions provide insight about the page or application where user activity occurred.

insightPlaybackLocationType
Data in the report is aggregated based on the type of page or application where video playbacks occurred. Possible values for this dimension are:

  • BROWSE – The data describes views that took place on the YouTube home page or home screen, in the user's subscription feed, or in another YouTube browsing feature.

  • CHANNEL – The data describes views that occurred on a channel page.

  • EMBEDDED – The data describes views that occurred on another website or application where the video was embedded using an <iframe> or <object> embed.

  • EXTERNAL_APP – The data describes views that occurred in a third-party application where the video was played using a method other than an <iframe> or <object> embed. For example, playbacks in applications that use the YouTube Android Player API would be categorized using this value.

  • MOBILE – The data describes views that occurred on YouTube's mobile website or on approved YouTube API clients, including mobile devices.

    As of September 10, 2013, playbacks are no longer categorized as MOBILE playbacks in YouTube Analytics reports. The value may remain in reports since legacy data still falls under that category. However, following that date, mobile playbacks are classified as either WATCH, EMBEDDED, or EXTERNAL_APP playbacks, depending on the type of application where the playbacks occur.

  • SEARCH – The data describes views that took place directly on the YouTube search results page.

  • WATCH – The data describes views that occurred on the video's YouTube watch page or in an official YouTube application, such as the YouTube Android app.

  • YT_OTHER – The data describes views that are not otherwise classified.

insightPlaybackLocationDetail
Data is aggregated based on the page where the player is located. Note that this report is only supported for views that occurred in embedded players, and it identifies the embedded players that generated the most views for a specified video. Thus, it provides a more fine-grained view than the playback location report by identifying the URLs or applications associated with the top embedded players.

Examples

The following sample requests use playback location dimensions:

  • Channel examples

    • Playback location
      • Viewcounts and watch time from different playback locations
      • Daily view counts and watch time from different playback locations
      • Top 10 – Third-party sites that generate the most views for an embedded video
      • Playlist view counts and watch time from different playback locations
      • Daily playlist view counts and watch time from different playback locations

  • Content owner examples

    • Playback location
      • Viewcounts and watch time from different playback locations
      • Daily view counts and watch time from different playback locations
      • Top 10 – Third-party sites that generate the most views for an embedded video
      • Playlist view counts and watch time from different playback locations
      • Daily playlist view counts and watch time from different playback locations

Playback details

creatorContentType
This dimension identifies the type of content associated with the user activity metrics in the data row. Data for this dimension is available for dates beginning January 1, 2019.

The following table lists dimension values:
Values
LIVE_STREAM The viewed content was a YouTube livestream.
SHORTS The viewed content was a YouTube Short.
STORY The viewed content was a YouTube Story.
VIDEO_ON_DEMAND The viewed content was a YouTube video that does not fall under one of the other dimension values.
UNSPECIFIED The content type of the viewed content is unknown.
liveOrOnDemand
This dimension indicates whether the user activity metrics in the data row are associated with views of a live broadcast. Data for this dimension is available for dates beginning April 1, 2014.

The following table lists dimension values:
Values
LIVE The row's data describes user activity that occurred during a live broadcast.
ON_DEMAND The row's data describes user activity that did not occur during a live broadcast.
subscribedStatus
This dimension indicates whether the user activity metrics in the data row are associated with viewers who were subscribed to the video's or playlist's channel. Possible values are SUBSCRIBED and UNSUBSCRIBED.

Note that the dimension value is accurate as of the time that the user activity occurs. For example, suppose a user has not subscribed to a channel and watches one of that channel's videos, then subscribes to the channel and watches another video, all on the same day. The channel's report indicates that one view has a subscribedStatus value of SUBSCRIBED, and one view has a subscribedStatus value of UNSUBSCRIBED.
youtubeProduct
This dimension identifies the YouTube service on which the user activity occurred. Data for this dimension is available as of July 18, 2015.

The following table lists dimension values:
Values
CORE The user activity that did not occur in one of the specialty YouTube applications (YouTube Gaming, YouTube Kids, or YouTube Music). Exception: User activity that occurred in YouTube Music before March 1, 2021, is included in CORE.
GAMING The user activity occurred in YouTube Gaming.
KIDS The user activity occurred in YouTube Kids.
MUSIC The user activity occurred in YouTube Music on or after March 1, 2021. Data prior to March 1, 2021 is included in CORE. Real-time data is not recorded.
UNKNOWN The user activity occurred prior to July 18, 2015.

Traffic sources

insightTrafficSourceType
Data in the report is aggregated based on the referrer type, which describes the manner in which users reached the video. Possible values for this dimension are:
  • ADVERTISING – The viewer was referred to the video by an advertisement. If you filter based on this traffic source, the insightTrafficSourceDetail field identifies the type of advertisement.
  • ANNOTATION – Viewers reached the video by clicking on an annotation in another video.
  • CAMPAIGN_CARD – Views originated from claimed, user-uploaded videos that the content owner used to promote the viewed content. This traffic source is only supported for content owner reports.
  • END_SCREEN – The views were referred from the end screen of another video.
  • EXT_URL – The video views were referred from a link on another website. If you filter based on this traffic source, the insightTrafficSourceDetail field identifies the web page. This traffic source includes referrals from Google Search results.
  • HASHTAGS – Views originated from VOD hashtag pages or Shorts hashtag pivot pages.
  • LIVE_REDIRECT - The video views were referred from Live Redirects.
  • NO_LINK_EMBEDDED – The video was embedded on another website when it was viewed.
  • NO_LINK_OTHER – YouTube did not identify a referrer for the traffic. This category encompasses direct traffic to a video as well as traffic on mobile apps.
  • NOTIFICATION – The video views were referred from an email or notification from YouTube.
  • PLAYLIST – The video views occurred while the video was being played as part of a playlist. It includes traffic coming from the playlist page.
  • PRODUCT_PAGE - The video views were referred from a Product page.
  • PROMOTED – The video views were referred from an unpaid YouTube promotion, such as the YouTube "Spotlight Videos" page.
  • RELATED_VIDEO – The video views were referred from a related video listing on another video watch page. If you filter based on this traffic source, the insightTrafficSourceDetail field specifies the video ID for that video.
  • SHORTS – The viewer was referred by swiping vertically from the previous video in the Shorts viewing experience.
  • SOUND_PAGE – Views originated from Shorts sound pivot pages.
  • SUBSCRIBER – The video views were referred from feeds on the YouTube homepage or from YouTube subscription features. If you filter based on this traffic source, the insightTrafficSourceDetail field specifies the homepage feed items or other page from which views were referred.
  • YT_CHANNEL – The video views occurred on a channel page. If you filter based on this traffic source, the insightTrafficSourceDetail field specifies the channel ID for that channel.
  • YT_OTHER_PAGE – The video views were referred from a link other than a search result or related video link that appeared on a YouTube page. If you filter based on this traffic source, the insightTrafficSourceDetail field identifies the page.
  • YT_SEARCH – The video views were referred from YouTube search results. If you filter based on this traffic source, the insightTrafficSourceDetail field specifies the search term.
  • VIDEO_REMIXES – The video views were referred from the remixed video link in the Shorts player. If you filter based on this traffic source, the insightTrafficSourceDetail field specifies the video from which the viewer was referred.
insightTrafficSourceDetail
Data in the report is aggregated based on the referrers that generated the most views for a specified video and a specified traffic source type. The following list identifies the traffic sources for which this report is available. For each traffic source, the list identifies the information that the insightTrafficSourceDetail dimension provides.
  • ADVERTISING – The type of advertisement that led to the views. Possible values are:
    • Click-to-play engagement ad
    • Engagement ad
    • Google Search ads
    • Homepage video ad
    • Reserved skippable in-stream
    • TrueView in-search and in-display
    • TrueView in-stream
    • Uncategorized YouTube advertising
    • Video wall
  • CAMPAIGN_CARD – The claimed video that led viewers to the video identified in the report.
  • END_SCREEN – The video that led viewers to the video identified in the report.
  • EXT_URL – The website that referred the viewers to the video.
  • HASHTAGS – The hashtag that led to the views.
  • NOTIFICATION – The email or notification that referred the traffic.
  • RELATED_VIDEO – The related video that led viewers to the video covered in the report.
  • SOUND_PAGE – The video that led to the views.
  • SUBSCRIBER – The homepage feed item or YouTube subscription feature that led viewers to the video covered in the report. Valid values are:
    • activity – Views from items in homepage subscription feeds that resulted from non-upload and non-social channel activity, including likes, favorites, bulletin posts, and playlist additions.
    • blogged – Views from items in homepage subscription feeds that resulted from links from top blogs.
    • mychannel – Views from items in other feeds listed on the homepage, such as "Likes," "Watch History," and "Watch Later."
    • podcasts – Views originating from items in the Podcasts destination page.
    • sdig – Views originating from subscription update emails.
    • uploaded – Views from the uploaded items in homepage subscription feeds.
    • / – Other views originating from the YouTube homepage.
    • /my_subscriptions – Views originating from users' My subscriptions pages on YouTube.
  • YT_CHANNEL – The channel page where viewers watched the video.
  • YT_OTHER_PAGE – The YouTube page from which viewers were referred to the video.
  • YT_SEARCH – The search term that led viewers to the video.
  • VIDEO_REMIXES – The video that led to the views.

Examples

The following sample requests use traffic source dimensions:

  • Channel examples

    • Traffic source
      • Viewcounts and watch time from different traffic sources in a country
      • Daily view counts and watch time from different traffic sources
      • Top 10 – YouTube search terms that generate the most traffic for a video
      • Top 10 – Google Search terms that generate the most traffic for a video
      • Playlist view counts and watch time from different traffic sources in a country
      • Daily playlist view counts and watch time from different traffic sources

  • Content owner examples

    • Traffic source
      • Viewcounts and watch time from different traffic sources
      • Daily view counts and watch time from different traffic sources
      • Top 10 – YouTube search terms that generate the most traffic for a video
      • Top 10 – Google Search terms that generate the most traffic for a video
      • Playlist view counts and watch time from different traffic sources in a country
      • Daily playlist view counts and watch time from different traffic sources

Devices

deviceType
This dimension identifies the physical form factor of the device on which the view occurred. The following list identifies the device types for which the API returns data. You can also use the deviceType dimension as a filter to restrict an operating system report to only contain data for a specific type of device.
  • DESKTOP
  • GAME_CONSOLE
  • MOBILE
  • TABLET
  • TV
  • UNKNOWN_PLATFORM
operatingSystem
This dimension identifies the software system of the device on which the view occurred. The following list identifies the operating systems for which the API returns data. You can also use the operatingSystem as a filter to restrict a device type report to only contain data for a specific operating system.
  • ANDROID
  • BADA
  • BLACKBERRY
  • CHROMECAST
  • DOCOMO
  • FIREFOX
  • HIPTOP
  • IOS
  • KAIOS
  • LINUX
  • MACINTOSH
  • MEEGO
  • NINTENDO_3DS
  • OTHER
  • PLAYSTATION
  • PLAYSTATION_VITA
  • REALMEDIA
  • SMART_TV
  • SYMBIAN
  • TIZEN
  • VIDAA
  • WEBOS
  • WII
  • WINDOWS
  • WINDOWS_MOBILE
  • XBOX

Examples

The following sample requests use device dimensions:

  • Channel examples

    • Device/OS
      • Daily device type metrics for the Android operating system
      • Daily operating system metrics for mobile devices
      • Daily operating system and device type metrics
      • Daily device type metrics for playlist views on the Android operating system
      • Daily operating system metrics for playlist views on mobile devices

  • Content owner examples

    • Device/OS
      • Daily device type metrics for claimed videos
      • Daily operating system metrics for claimed videos viewed on mobile devices
      • Daily operating system and device type metrics
      • Daily device type metrics for playlist views on the Android operating system
      • Daily operating system metrics for playlist views on mobile devices

Demographics

Demographic dimensions help you to understand the age range and gender distribution of your audience. The YouTube Help Center contains additional information about demographic data in YouTube Analytics reports.

ageGroup (core dimension)
This dimension identifies the age group of the logged-in users associated with the report data. The API uses the following age groups:
  • age13-17
  • age18-24
  • age25-34
  • age35-44
  • age45-54
  • age55-64
  • age65-
This is a core dimension and is subject to the Deprecation Policy.
gender (core dimension)
This dimension identifies the gender of the logged-in users associated with the report data. Valid values are female, male and user_specified. This is a core dimension and is subject to the Deprecation Policy.

Examples

The following sample requests use demographic dimensions:

  • Channel examples

    • Demographic
      • Viewer demographics in California (age group and gender)
      • Playlist viewer demographics in California (age group and gender)

  • Content owner examples

    • Demographic
      • Viewer demographics in California (age group and gender)
      • Playlist viewer demographics in California (age group and gender)

Engagement and content sharing

sharingService (core dimension)
This dimension identifies the service that was used to share videos. Videos can be shared on YouTube (or via the YouTube player) using the "Share" button. This is a core dimension and is subject to the Deprecation Policy.

The following table lists valid dimension values:
Sharing service API value
Ameba AMEBA
Android Email ANDROID_EMAIL
Android Messenger ANDROID_MESSENGER
Android messaging ANDROID_MMS
Blackberry Messenger BBM
Blogger BLOGGER
Copy to Clipboard COPY_PASTE
Cyworld CYWORLD
Digg DIGG
Dropbox DROPBOX
Embed EMBED
Email MAIL
Facebook FACEBOOK
Facebook Messenger FACEBOOK_MESSENGER
Facebook Pages FACEBOOK_PAGES
Fotka FOTKA
Gmail GMAIL
goo GOO
Google+ GOOGLEPLUS
Go SMS GO_SMS
GroupMe GROUPME
Hangouts HANGOUTS
hi5 HI5
HTC text message HTC_MMS
Google Inbox INBOX
iOS System Activity Dialog IOS_SYSTEM_ACTIVITY_DIALOG
KAKAO Story KAKAO_STORY
Kakao (Kakao Talk) KAKAO
Kik KIK
LGE Email LGE_EMAIL
Line LINE
Linkedin LINKEDIN
LiveJournal LIVEJOURNAL
menéame MENEAME
mixi MIXI
Motorola Messaging MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
Nearby Share NEARBY_SHARE
NUjij NUJIJ
Odnoklassniki (Одноклассники) ODNOKLASSNIKI
Other OTHER
Pinterest PINTEREST
Rakuten (楽天市場) RAKUTEN
reddit REDDIT
Skype SKYPE
Skyrock SKYBLOG
Sony Conversations SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
Text message TEXT_MESSAGE
Tuenti TUENTI
tumblr. TUMBLR
Twitter TWITTER
Unknown UNKNOWN
Verizon messages VERIZON_MMS
Viber VIBER
VKontakte (ВКонтакте) VKONTAKTE
WeChat WECHAT
Weibo WEIBO
WhatsApp WHATS_APP
Wykop WYKOP
Yahoo! Japan YAHOO
YouTube Gaming YOUTUBE_GAMING
YouTube Kids YOUTUBE_KIDS
YouTube Music YOUTUBE_MUSIC
YouTube TV YOUTUBE_TV

See the help docs for more information.

Examples

The following sample requests use social dimensions:

  • Channel examples

    • Social: Sharing metrics, aggregated by service where videos were shared

  • Content owner examples

    • Social: Sharing metrics, aggregated by service where videos were shared

Audience retention

elapsedVideoTimeRatio
This dimension specifies the ratio of the elapsed portion of the video to the video's length. Retention dimensions and metrics are used to measure audience retention over time, and the elapsedVideoTimeRatio dimension is the time measurement. For example, a value of 0.4 indicates that the corresponding report data shows retention data after 40 percent of the video has elapsed.

The API returns 100 data points for each video with ratio values ranging from 0.01 to 1.0. The times at which data is measured during video playbacks are equally spaced for each video. This means that for a two-minute video, the interval between data points is 1.2 seconds. However, for a two-hour video, the interval between data points is 72 seconds. The dimension's value denotes the exclusive end of the interval.
audienceType (filter only)
The dimension value identifies the type of traffic associated with the report data. Supported values are ORGANIC, AD_INSTREAM, and AD_INDISPLAY. See the YouTube Help Center for explanations of these traffic source types.

Note that data for the audienceType filter is available as of September 25, 2013. The API does not return data for queries that use the filter to try to retrieve data from earlier dates. Queries that do not use the filter work for any date after July 1, 2008.

Examples

The following sample requests use audience retention dimensions:

Live streaming

livestreamPosition
This dimension specifies a particular minute during a live video stream. The report metrics indicate how many users were watching the livestream at that time.

Membership cancellations

membershipsCancellationSurveyReason
The number of surveys completed by YouTube users who canceled their channel membership for the specified channel during the reporting period. The following table lists valid dimension values:
API value Explanation
UNKNOWN The user did not complete the survey.
DISLIKE_PERKS The user did not like the perks of the membership.
PERKS_NOT_DELIVERED The user said promised membership perks were not delivered.
CANNOT_ACCESS_PERKS The user was not able to access the perks.
NO_LONGER_INTERESTED The user is no longer interested in the channel membership.
FEEL_UNAPPRECIATED The user felt unappreciated as a channel member.
FINANCIAL_REASONS The user canceled for financial reasons.
JOIN_LIMITED_TIME The user only intended to join for a limited time.
OTHER The user had another reason for canceling.

Ad performance

adType
The adType dimension is used in ad performance reports and aggregates the requested metrics based on the types of ads that ran during video playbacks. The following list explains possible dimension values. See the YouTube Help Center for more information about YouTube advertising formats.

  • auctionBumperInstream – Non-skippable video ads, placed via auction, of up to 6 seconds that must be watched before a video can be viewed.

  • auctionDisplay – A rich media or image ad that appears either as an overlay on the bottom of the video player, as a 300x250 ad unit on the video watch page, or as a combination of both. When the overlay runs, it automatically closes after displaying for a certain amount of time, and the user can close the overlay as well. If an overlay and a banner are shown together, each ad is counted as a separate impression.

  • auctionInstream – Non-skippable video ads that run before, during, or after the main video.

  • auctionTrueviewInslate – The viewer chooses one of several video ads from a selection of choices displayed before a video. See the TrueView documentation for more information.

  • auctionTrueviewInstream – Skippable video ads that run before or during the main video. See the TrueView documentation for more information.

  • auctionUnknown – An ad that was purchased via the AdWords auction but that has not been classified into one of the other ad types.

  • reservedBumperInstream – Non-skippable video ads, sold on a reserved basis, of up to 6 seconds that must be watched before a video can be viewed.

  • reservedClickToPlay – A video ad that the user must click to initiate playback. An ad impression is recorded any time the click-to-play ad unit displays, regardless of whether the user initiates a playback. These are sold on a reserved basis.

  • reservedDisplay – A rich media or image ad that appears either as an overlay on the bottom of the video player, as a 300x250 ad unit on the video watch page, or as a combination of both. When the overlay runs, it automatically closes after displaying for a certain amount of time, and the user can close the overlay as well. If an overlay and a banner are shown together, each ad is counted as a separate impression.

  • reservedInstream – Non-skippable video ads that are inserted before, during, or after the main video.

  • reservedInstreamSelect

  • reservedMasthead – A large ad, which can include video and graphic elements, that appears on the homepage.

  • reservedUnknown – An ad that was sold on a reserved basis that could not be classified into one of the other ad types.

  • unknown – YouTube could not classify this ad type.

Examples

The following sample reports retrieve ad performance or revenue metrics:

  • Channel examples

    • Revenue/Ads
      • Channel revenue and ad performance metrics
      • Daily revenue and ad performance metrics
      • Country-specific revenue and ad performance metrics
      • Top 10 – Videos with the highest revenue
      • Ad performance metrics for different ad types

  • Content owner examples

    • Revenue/Ads
      • Revenue and ad performance metrics for claimed content
      • Daily revenue and ad performance metrics
      • Country-specific revenue and ad performance metrics
      • Top 10 – Videos with the highest revenue
      • Ad performance metrics for different ad types

Playlists

isCurated (filter only)
This filter indicates that the request is retrieving data about video views that occurred in the context of a playlist.

Examples

All of the sample requests that retrieve playlist reports use the isCurated filter.

Content owner dimensions

The following dimensions are only supported for content owner reports.

Important: API requests to retrieve content owner reports must filter data using one of the following dimensions:
  • video
  • channel
  • A supported combination of the claimedStatus and uploaderType dimensions as defined below.
claimedStatus (only used in content owner reports)
This dimension lets you indicate that an API response should only contain metrics for claimed content. The only valid value for this dimension is claimed. If the filters parameter restricts the query to claimedStatus==claimed, the API will only retrieve data for claimed content. The table in the definition of the uploaderType dimension provides more detail about how to use this dimension.
uploaderType (core dimension) (only used in content owner reports)
This dimension lets you indicate whether an API response should contain metrics for content uploaded by the specified content owner and/or content uploaded by third parties, such as user-uploaded videos. Valid values are self and thirdParty. This is a core dimension and is subject to the Deprecation Policy.

The table below shows the supported combinations for the claimedStatus and uploaderType dimensions, which are both used in the filters parameter:

claimedStatus value uploaderType value Description
[Not set] self Retrieves YouTube Analytics data for claimed and unclaimed content uploaded by the content owner.
claimed [Not set] Retrieves data for claimed content uploaded by the content owner or by a third party.
claimed self Retrieves data for claimed content uploaded by the content owner.
claimed thirdParty Retrieves data for claimed content uploaded by a third party.

Examples

Many of the sample API requests for content owner reports use a supported combination of the claimedStatus and uploaderType dimensions to filter data.