Data reference - Adriel Knowledge Base

Introduction

YouTube Analytics is the channel-level reporting data source for a YouTube channel you own. It reads user-activity data — views, watch time, engagement, subscribers, cards and annotations, and playlist activity — from the YouTube Analytics API v2, authorized by the channel owner. This is distinct from the YouTube Public connector, which reports publicly visible metrics for videos and channels you do not own. Each data source is configured against one report template at creation time. The available metrics and breakdowns are governed by that template, so a single data source exposes a focused, YouTube-approved slice of the catalog rather than the full metric list at once. Video and playlist titles, thumbnails, and publish dates are enriched from the YouTube Data API v3, because the Analytics API returns only IDs. As an analytics connector, view, watch-time, engagement, and breakdown data are standardized so widgets can aggregate alongside other sources. To connect this data source, see How to connect YouTube Analytics to Adriel.

Data refresh strategy

Architecture data

Architecture covers the channel plus its catalog of videos and playlists and their metadata (title, thumbnail, publish date). This catalog is fetched from the YouTube Data API v3 and refreshed as part of the daily cache cycle. A data source reports on up to 300 videos, sorted by publication date; newly published videos beyond that window are not added.

Reports data

Reports data — the metrics and breakdowns of the selected report template — is served from a cache rather than fetched live on each dashboard load. The cache is refreshed daily at 05:00 UTC by default. A manual refresh is available, limited to one refresh per data source per day. Because reporting is cache-based, a dashboard shows the data captured at the last successful refresh. YouTube also finalizes analytics on a delay, so the most recent days may still change.

Architecture levels

Configuration is a three-level hierarchy chosen at setup and fixed after creation: Report type → Detailed report type → Report template

Report type — Channel Reports (the only report type currently offered).
Detailed report type — Video Reports or Playlist Reports.
Report template — one named template that fixes the breakdowns, metrics, and filters for the data source.

Video Reports offer 12 templates and Playlist Reports offer 9:

Report template	Video Reports	Playlist Reports
Basic Stats	Yes	Yes
User geography	Yes	Yes
User geography by U.S. province	Yes	Yes
Playback locations	Yes	Yes
Playback location detail	Yes	Yes
Traffic sources	Yes	Yes
Traffic source detail	Yes	Yes
Device type and operating system	Yes	Yes
Viewer demographics	Yes	Yes
Engagement and content sharing	Yes	—
Audience retention	Yes	—
Concurrent viewers (for livestreams)	Yes	—

The metrics and breakdowns available on a data source are locked to its selected template and cannot be changed after creation. To report on a different template, create another data source.

Date range limits

Due to quota limits set by Adriel, one year of historical data is available. Ranges older than one year before the data source’s fetch window are not retrieved.

Metrics

How to read the columnsCode style like views is the literal YouTube Analytics API v2 metric name. All metrics below are platform fields; none are derived by Adriel.Data type vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.

Availability depends on the selected report template. Not all metrics below are available at the same time — each data source exposes only the subset defined by its report template, and metrics from different templates cannot be combined in one query.

Views & watch time

Metric	Description	Data type	API Key
Views	Number of times videos or playlists were viewed.	Number	`views`
Views (Premium)	Views by YouTube Premium (Red) members.	Number	`redViews`
Playlist views	Number of times a playlist was viewed.	Number	`playlistViews`
Minutes watched	Estimated total minutes watched.	Number	`estimatedMinutesWatched`
Minutes watched (Premium)	Estimated minutes watched by YouTube Premium members.	Number	`estimatedRedMinutesWatched`
Average view duration	Average length, in seconds, of each view.	Duration	`averageViewDuration`
Average view percentage	Average share of each video watched during a view.	Percentage	`averageViewPercentage`

Engagement

Metric	Description	Data type	API Key
Comments	Number of comments left on videos.	Number	`comments`
Likes	Number of likes.	Number	`likes`
Dislikes	Number of dislikes.	Number	`dislikes`
Shares	Number of times content was shared.	Number	`shares`
Videos added to playlists	Times a video was added to any playlist.	Number	`videosAddedToPlaylists`
Videos removed from playlists	Times a video was removed from any playlist.	Number	`videosRemovedFromPlaylists`

Subscribers

Metric	Description	Data type	API Key
Subscribers gained	Number of subscribers gained.	Number	`subscribersGained`
Subscribers lost	Number of subscribers lost.	Number	`subscribersLost`

Playlist activity

Metric	Description	Data type	API Key
Average time in playlist	Average time, in seconds, viewers spent watching a playlist per playlist view.	Duration	`averageTimeInPlaylist`
Playlist average view duration	Average length, in seconds, of a video view that started from a playlist.	Duration	`playlistAverageViewDuration`
Playlist estimated minutes watched	Estimated minutes watched for videos viewed in a playlist context.	Number	`playlistEstimatedMinutesWatched`
Playlist saves	Number of times a playlist was saved.	Number	`playlistSaves`
Playlist starts	Number of times viewers initiated playback of a playlist.	Number	`playlistStarts`
Views per playlist start	Average number of video views each time a playlist was started.	Ratio	`viewsPerPlaylistStart`

Cards & annotations

Metric	Description	Data type	API Key
Annotation CTR	Click-through rate for annotations.	Percentage	`annotationClickThroughRate`
Annotation close rate	Rate at which annotations were closed.	Percentage	`annotationCloseRate`
Annotation impressions	Total annotation impressions.	Number	`annotationImpressions`
Annotation clickable impressions	Annotations that were clickable.	Number	`annotationClickableImpressions`
Annotation closable impressions	Annotations that were closable.	Number	`annotationClosableImpressions`
Annotation clicked	Number of clicked annotations.	Number	`annotationClicks`
Annotation closed	Number of closed annotations.	Number	`annotationCloses`
Card click rate	Click-through rate for cards.	Percentage	`cardClickRate`
Card teaser click rate	Click-through rate for card teasers.	Percentage	`cardTeaserClickRate`
Card impressions	Number of times cards were shown.	Number	`cardImpressions`
Card teaser impressions	Number of times card teasers were shown.	Number	`cardTeaserImpressions`
Card clicks	Number of card clicks.	Number	`cardClicks`
Card teaser clicks	Number of card teaser clicks.	Number	`cardTeaserClicks`

Audience retention

Metric	Description	Data type	API Key
Audience watch ratio	Ratio of viewers watching a video at a given point relative to total views.	Ratio	`audienceWatchRatio`
Relative retention performance	How well a video retains viewers compared with similar-length YouTube videos.	Ratio	`relativeRetentionPerformance`
Started watching	Times viewers started watching a video segment.	Number	`startedWatching`
Stopped watching	Times viewers stopped watching a video segment.	Number	`stoppedWatching`
Total segment impressions	Segment impressions used to compute retention.	Number	`totalSegmentImpressions`

Demographics

Metric	Description	Data type	API Key
Viewer percentage	Share of the audience represented by each age group and gender.	Percentage	`viewerPercentage`

Livestream

Metric	Description	Data type	API Key
Average concurrent viewers	Average number of simultaneous viewers during a livestream.	Number	`averageConcurrentViewers`
Peak concurrent viewers	Highest number of simultaneous viewers during a livestream.	Number	`peakConcurrentViewers`

Breakdowns

How to read the columnsCode style like insightTrafficSourceType is the literal YouTube Analytics API v2 field name. As with metrics, the breakdowns available on a data source are governed by its report template.

Video

Video title, ID, publish date, and thumbnail are enriched by Adriel from the YouTube Data API v3, because the Analytics API returns only video IDs.

Breakdown	Description	API Key
Video	Video title.	`snippet.title`
Video ID	YouTube video identifier.	`contentDetails.videoId`
Video published at	Date and time the video was published.	`contentDetails.publishedAt`
Thumbnail	URL of the video’s default thumbnail.	`snippet.thumbnails.default.url`

Playlist

Playlist identity fields are enriched by Adriel from the YouTube Data API v3; they apply to Playlist Reports data sources.

Breakdown	Description	API Key
Playlist	Playlist title.	`playlist`
Playlist ID	YouTube playlist identifier.	`playlistId`
Playlist published at	Date and time the playlist was created.	`playlistPublishedAt`

Date

Breakdown	Description	API Key
Date	Date on which the activity occurred.	`day`

Geography

Breakdown	Description	API Key
Country	Country associated with the activity.	`country`
Province	U.S. state or territory (available on the U.S. province template).	`province`

Playback location

Breakdown	Description	API Key
Playback location type	Where playback occurred (e.g. watch page, embedded player).	`insightPlaybackLocationType`
Playback location detail	Specific players where embedded playback occurred.	`insightPlaybackLocationDetail`

Traffic source

Breakdown	Description	API Key
Traffic source type	Category of referrer that led to the view.	`insightTrafficSourceType`
Traffic source detail	Specific referrer within a traffic source type.	`insightTrafficSourceDetail`

Device & operating system

Breakdown	Description	API Key
Device type	Type of device on which playback occurred.	`deviceType`
Operating system	Operating system of the playback device.	`operatingSystem`

Viewer demographics

Breakdown	Description	API Key
Age group	Viewer age bracket.	`ageGroup`
Gender	Viewer gender.	`gender`

Breakdown	Description	API Key
Sharing service	Service used to share content (available on the engagement and content sharing template).	`sharingService`

Audience retention

Breakdown	Description	API Key
Elapsed video time ratio	Position within the video, expressed as a ratio of elapsed time to duration.	`elapsedVideoTimeRatio`

Livestream

Breakdown	Description	API Key
Livestream position	Position within a livestream (available on the concurrent viewers template).	`livestreamPosition`

Limitations

Based on the current connector, YouTube Analytics has:

A one-year historical window — set by Adriel due to quota limits (see Date range limits).
A 300-video cap per data source — reports cover a maximum of 300 videos, sorted by publication date. Playlist Reports have no explicit playlist cap.
Template-locked fields — the metrics and breakdowns available are fixed by the report template chosen at creation and cannot be changed afterward.
No cross-template combination — because each template aggregates on its own breakdown/metric combination, data from different templates cannot be mixed in one query without inconsistency or errors.
A data-finalization lag — YouTube finalizes analytics on a delay, so the most recent days may still change.
YouTube thresholding — some data (for example demographics) is withheld when metrics fall below undisclosed thresholds that YouTube may change at its discretion.
No rows for zero-activity dates — some reports omit dates on which no user activity occurred.
No deleted data — once a video or playlist is deleted on YouTube, its data is no longer available.
Single-video retention and livestream templates — the Audience retention and Concurrent viewers templates report on one target video at a time.
Channel Reports only — content-owner reports are not exposed.
Revenue and ad-performance metrics not surfaced — monetary metrics defined by the API are not available through Adriel’s report templates.

API references

YouTube Analytics API v2 — Reports: query
YouTube Analytics — Channel reports
YouTube Analytics Data API — reference
YouTube Analytics — Metrics
YouTube Data API v3 — channel, video, and playlist metadata

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Views & watch time

​Engagement

​Subscribers

​Playlist activity

​Cards & annotations

​Audience retention

​Demographics

​Livestream

​Breakdowns

​Video

​Playlist

​Date

​Geography

​Playback location

​Traffic source

​Device & operating system

​Viewer demographics

​Sharing

​Audience retention

​Livestream

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Views & watch time

Engagement

Subscribers

Playlist activity

Cards & annotations

Audience retention

Demographics

Livestream

Breakdowns

Video

Playlist

Date

Geography

Playback location

Traffic source

Device & operating system

Viewer demographics

Sharing

Audience retention

Livestream

Limitations

API references

See also