> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube Analytics

> Query views, watch time and subscribers for a YouTube channel live from Explore and AI agents

The YouTube Analytics [live data source](https://docs.lightdash.com/integrations/live-data-sources) reads one YouTube channel. Each query is one report request, and Lightdash shows the results as they come back from YouTube. It's a [level 3](https://docs.lightdash.com/integrations/live-data-sources#integration-levels) integration: its API returns reports.

## Before you start

* **Live data sources enabled** for your organization. See [Live data sources](https://docs.lightdash.com/integrations/live-data-sources).
* **Admin role** in the Lightdash project.
* **A Google account that can read the channel's analytics.**

## Connect YouTube Analytics

1. On the nav bar, click **Browse** → **Semantic Layer**.
2. In the sidebar, select **Live data sources**, then click **Add**.
3. Select **YouTube Analytics**.
4. Enter a **Name**, such as `YouTube Analytics`.
5. Click **Continue to Google**.
6. Sign in with your Google account and allow read-only access to YouTube.
7. Back in Lightdash, pick the channel the source reads.

Lightdash adds a **Channel activity** table to Explore. Queries run with the Google account that signed in. To change it, choose **Sign in again** from the source's menu.

## Dimensions

| Dimension | Notes |
| - | - |
| Date | Per day |
| Date month | First day of the month |
| Video ID | Video titles aren't available |
| Country | Two-letter code, such as `US`. `ZZ` means unidentified |
| Device type | Such as `DESKTOP`, `MOBILE` or `TV` |
| Traffic source type | Such as `YT_SEARCH`, `RELATED_VIDEO` or `SUBSCRIBER` |
| Content type | `LIVE_STREAM`, `SHORTS`, `STORY`, `VIDEO_ON_DEMAND` or `UNSPECIFIED` |

Revenue, demographics, playlists and audience retention aren't available.

## Metrics

| Metric | Notes |
| - | - |
| Views, Engaged views | YouTube counts a view differently per report |
| Estimated minutes watched | |
| Average view duration | In seconds, per playback. Don't add rows together |
| Average view percentage | From 0 to 100, per playback. Don't add rows together |
| Likes, Dislikes, Comments, Shares | |
| Subscribers gained, Subscribers lost | |

## Combination rules

YouTube answers a fixed set of reports. A query can break down by one of these:

* **Date** or **Date month**
* **Country**
* **Video ID**
* **Device type**, optionally with **Date**
* **Traffic source type**, optionally with **Date**

You can add **Content type** to any of them, but it can't be used alone. A query with no dimensions returns channel totals.

Some reports have further rules:

* **Device type** and **Traffic source type** only work with Views, Engaged views and Estimated minutes watched.
* **Video ID** returns at most 200 videos, ranked from highest to lowest. Sort by one of Views, Estimated minutes watched, Subscribers gained or Subscribers lost.
* **Date month** only reads whole months. Filter Date to start on the first of a month and end on the last of a month or today.

Lightdash checks these rules before calling YouTube and tells you what to change.

## Supported features

| Feature | Available |
| - | - |
| Filters on Video ID, up to 500 values | Yes, exact match |
| Filters on Country, one value | Yes, exact match |
| Filters on other dimensions | No |
| Filters on metrics | No |
| OR filters and nested filter groups | No |
| Table calculations, custom metrics and custom dimensions | No |
| Period-over-period comparisons, pivots and date zoom | No |

A query can't filter by a dimension and break down by it at the same time.

## Limits

| Limit | Value |
| - | - |
| Default date range | Last 28 days, when the query has no filter on Date. Last 12 full months for **Date month** |
| Most rows per query | 9,999. 200 for **Video ID** |
| Timeout | 30 seconds |
| Queries at once | 5 per source |
| Calls per minute | 60 per source |
| Calls per hour | 1,000 per source |

YouTube leaves out the most recent days until all their metrics are ready, so the latest dates can be missing. YouTube also applies its own quotas.

## Example questions

* *"Views and watch time by day over the last 28 days."*
* *"Top 20 videos by estimated minutes watched this month."*
* *"Views by traffic source type last week."*

## Troubleshooting

**The latest days are missing.** YouTube publishes a day's data once all its metrics are ready. Check again later, or end the date range earlier.

**YouTube has no report for your combination.** See [Combination rules](#combination-rules) and remove a dimension.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.