> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data reference
> Metrics, breakdowns, refresh cadence, and limits for the YouTube Analytics data source in Adriel.
## 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-sources/o-z/youtube-analytics/how-to-connect).
## 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**
1. **Report type** — Channel Reports (the only report type currently offered).
2. **Detailed report type** — Video Reports or Playlist Reports.
3. **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 columns**
Code 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 columns**
Code 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` |
### Sharing
| 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](https://developers.google.com/youtube/analytics/reference/reports/query)
* [YouTube Analytics — Channel reports](https://developers.google.com/youtube/analytics/channel_reports)
* [YouTube Analytics Data API — reference](https://developers.google.com/youtube/analytics)
* [YouTube Analytics — Metrics](https://developers.google.com/youtube/analytics/metrics)
* [YouTube Data API v3](https://developers.google.com/youtube/v3) — channel, video, and playlist metadata
## See also
* [How to connect YouTube Analytics](/data-sources/o-z/youtube-analytics/how-to-connect) (paired how-to)
* [YouTube Public data reference](/data-sources/o-z/youtube-public/data-reference) — for public metrics on channels and videos you do not own
* [Google Analytics 4 data reference](/data-sources/g-n/google-analytics-4/data-reference) — for the web and app analytics counterpart