> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/marketing/youtube.md).

# YouTube

Export YouTube channel and video performance data to Google Sheets, BigQuery, or Claude via Coupler.io analytics integration.

YouTube is a video sharing platform with built-in analytics tools. Coupler.io connects to YouTube Analytics to automatically export your channel and video performance data to Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like Claude and ChatGPT.

## Why connect YouTube to Coupler.io?

* **Automated reporting** — Pull analytics data on a schedule without manual exports
* **Multiple report types** — Access channel statistics, video performance, traffic sources, subscriber data, and custom reports
* **Flexible breakdowns** — Split data by day or month, and filter by content type, device, geography, and more
* **Integrate with BI tools** — Send data directly to BigQuery, Looker Studio, Power BI, or spreadsheets for dashboards and analysis

## Prerequisites

* A YouTube account with access to the channels you want to report on
* YouTube Partner Program eligibility (for revenue-related metrics)
* Basic YouTube analytics access (available on most channels)

## Quick start

{% hint style="success" %}
Start with **Channel detailed statistics** if you're new to YouTube reporting. It gives you views, watch time, subscribers gained, and other essential metrics without complex setup.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Sign in to your Coupler.io account** and create a new data flow. Select **YouTube** as your source.
{% endstep %}

{% step %}
**Click "Connect" or "Sign in with Google"** to authorize Coupler.io to access your YouTube Analytics data. You'll be taken to Google's login page. Sign in with the account that owns or has access to your YouTube channels.
{% endstep %}

{% step %}
**Select your channels** from the dropdown. If you have multiple channels, you can select one or multiple to include in your report.
{% endstep %}

{% step %}
**Choose a report type**:

* **Channel detailed statistics** — Overall channel performance (views, watch time, subscribers, likes, comments)
* **Channel statistics by content and subscriber type** — Performance broken down by content type and subscriber status
* **Channel subscribers** — Subscriber growth with demographic breakdowns (age, gender, country)
* **Video detailed statistics** — Individual video performance metrics
* **Video statistics by content and subscriber type** — Video performance by content and subscriber type
* **Traffic sources** — Where your views come from (search, recommended, external links, etc.)
* **Custom** — Pick specific metrics and dimensions for a tailored report
  {% endstep %}

{% step %}
**Set your report period** using the start and end date fields. You can use specific dates or date macros (e.g., {{today}}, {{30daysago}}) to keep reports current.
{% endstep %}

{% step %}
**If using a preset report type**, you'll see additional options:

* **Split data by period** — Choose Day or Month to break down data into smaller time intervals
* **Additional dimensions** — Further segment your data by video, playlist, traffic source, or audience demographics
  {% endstep %}

{% step %}
**If using Custom report**, select your metrics (views, watch time, likes, subscribers gained, etc.) and dimensions (video, device type, country, age, gender, etc.) to build exactly what you need.
{% endstep %}

{% step %}
**Choose your destination** — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude or ChatGPT. Configure column mapping if needed.
{% endstep %}

{% step %}
**Run the data flow** by clicking the "Run" button. Wait for the flow to complete successfully before scheduling. This ensures your settings are correct and data flows as expected.
{% endstep %}
{% endstepper %}

## YouTube data overview

YouTube Analytics provides detailed performance data across your channels and videos. The metrics and dimensions you can pull depend on your report type.

## Report types

| Report Type                                       | Data Granularity                                       | Typical Use Case                                      |
| ------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------- |
| Channel detailed statistics                       | Channel-level daily or monthly                         | Dashboard tracking overall channel health             |
| Channel statistics by content and subscriber type | By content type (live/on-demand) and subscriber status | Understanding how different audience segments perform |
| Channel subscribers                               | Subscriber growth with demographics                    | Tracking audience growth and composition              |
| Video detailed statistics                         | Per-video daily or monthly                             | Analyzing individual video performance over time      |
| Video statistics by content and subscriber type   | Per-video by content type and subscriber status        | Comparing how videos perform across audience segments |
| Traffic sources                                   | By traffic source type (search, recommended, external) | Identifying where views come from                     |
| Custom                                            | Any metrics × any dimensions                           | Tailored analysis for specific business questions     |

## Available metrics

#### Engagement metrics

These measure how viewers interact with your content.

| Metric                  | Description                                   | Report Availability               |
| ----------------------- | --------------------------------------------- | --------------------------------- |
| Views                   | Total number of times your videos were viewed | All reports                       |
| Watch time (minutes)    | Total minutes watched across your content     | All reports                       |
| Average view duration   | Average minutes watched per view              | Video reports, custom             |
| Average view percentage | Average % of video watched per view           | Video reports, custom             |
| Likes                   | Number of likes received                      | Channel and video reports         |
| Dislikes                | Number of dislikes received                   | Channel and video reports         |
| Comments                | Number of comments on videos                  | Channel and video reports         |
| Shares                  | Number of times videos were shared            | Channel and video reports         |
| Annotation clicks       | Clicks on cards and annotations               | Channel and video reports, custom |

#### Subscriber metrics

These track subscriber activity and growth.

| Metric                         | Description                                        | Report Availability     |
| ------------------------------ | -------------------------------------------------- | ----------------------- |
| Subscribers gained             | New subscribers in the period                      | Channel reports, custom |
| Subscribers lost               | Subscribers who unsubscribed                       | Channel reports, custom |
| Audience watch ratio           | Watch time per subscriber                          | Channel reports, custom |
| Relative retention performance | How your videos retain viewers vs. YouTube average | Channel reports, custom |

#### Card & annotation metrics

These measure interactive elements on videos.

| Metric                        | Description                                            | Report Availability |
| ----------------------------- | ------------------------------------------------------ | ------------------- |
| Card clicks                   | Clicks on cards (info, poll, video, playlist, channel) | Custom reports      |
| Card impressions              | Times cards were shown                                 | Custom reports      |
| Card click rate               | % of views that clicked a card                         | Custom reports      |
| Annotation clicks             | Total annotation interaction clicks                    | Custom reports      |
| Annotation impressions        | Times annotations were shown                           | Custom reports      |
| Annotation click-through rate | % of views that clicked annotations                    | Custom reports      |

#### Playlist metrics

These apply to playlist-specific performance.

| Metric                        | Description                                       | Report Availability      |
| ----------------------------- | ------------------------------------------------- | ------------------------ |
| Playlist starts               | Number of times a playlist started playing        | Playlist reports, custom |
| Playlist views                | Total views of videos in a playlist               | Playlist reports, custom |
| Playlist watch time           | Total minutes watched in playlists                | Playlist reports, custom |
| Videos added to playlists     | How many times videos were added to playlists     | Playlist reports, custom |
| Videos removed from playlists | How many times videos were removed from playlists | Playlist reports, custom |

#### Audience metrics

These provide demographic and device information.

| Metric               | Description                            | Report Availability               |
| -------------------- | -------------------------------------- | --------------------------------- |
| Viewer percentage    | % of views from a specific demographic | Custom with audience dimensions   |
| Audience watch ratio | Viewing patterns by audience segment   | Custom with demographic breakdown |

#### YouTube Premium metrics

These track performance from Premium members (if applicable).

| Metric                     | Description                     | Report Availability |
| -------------------------- | ------------------------------- | ------------------- |
| YouTube Premium views      | Views from Premium members      | Custom reports      |
| YouTube Premium watch time | Watch time from Premium members | Custom reports      |

## Available dimensions

#### Temporal dimensions

Break data down by time periods.

| Dimension                | Description                             | Applies To                                     |
| ------------------------ | --------------------------------------- | ---------------------------------------------- |
| Day                      | Individual calendar days                | Time-series analysis in all splittable reports |
| Month                    | Monthly grouping                        | Monthly reports and aggregations               |
| Elapsed video time ratio | How far through a video viewers watched | Viewer retention analysis                      |

#### Video & content dimensions

Identify performance by video or content characteristics.

| Dimension           | Description                     | Applies To                |
| ------------------- | ------------------------------- | ------------------------- |
| Video               | Individual video title and ID   | Video reports, custom     |
| Playlist            | Individual playlist name        | Playlist reports, custom  |
| Content type        | Live vs. on-demand videos       | Content breakdown reports |
| Live or on demand   | Explicit live/on-demand flag    | Content reports           |
| Subscription status | Premium vs. non-Premium viewers | Subscriber breakdowns     |

#### Audience demographics

Understand your viewers by characteristics.

| Dimension | Description                                               | Applies To                                |
| --------- | --------------------------------------------------------- | ----------------------------------------- |
| Age       | Viewer age group (18-24, 25-34, 35-44, 45-54, 55-64, 65+) | Subscriber and custom demographic reports |
| Gender    | Male, female, or unspecified                              | Subscriber and custom demographic reports |
| Country   | Viewer's country of origin                                | Geographic reports, custom                |
| City      | Viewer's city (US data)                                   | Geographic reports, custom                |
| Province  | Viewer's US state                                         | US-only geographic reports                |

#### Device & platform dimensions

See how audiences access content.

| Dimension        | Description                                      | Applies To                      |
| ---------------- | ------------------------------------------------ | ------------------------------- |
| Device type      | Mobile, desktop, TV, or tablet                   | Custom device breakdown reports |
| Operating system | Windows, macOS, iOS, Android, etc.               | Custom OS breakdown reports     |
| YouTube product  | YouTube, YouTube TV, YouTube Music, YouTube Kids | Subscription status reports     |

#### Traffic source dimensions

Identify how viewers discover your content.

| Dimension                     | Description                                                                                          | Applies To                    |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------- |
| Insight traffic source type   | Advertising, external links, related videos, search, subscriber feed, YouTube channel, YouTube pages | Traffic source reports        |
| Insight traffic source detail | Specific source (e.g., "Google Search" or "YouTube Search")                                          | Traffic source detail reports |
| Sharing service               | Platform shared from (Facebook, Twitter, email, etc.)                                                | Custom sharing analysis       |

## Common metric combinations

**Channel health dashboard:**

* Views, watch time, subscribers gained, likes, comments
* Broken by day for trending

**Audience retention analysis:**

* Average view percentage, average view duration, relative retention performance
* Segmented by video and device type

**Geographic performance:**

* Views, watch time, average view duration
* Broken by country and city

**Subscriber demographics:**

* New subscribers, watch time, viewer percentage
* Segmented by age, gender, and country

**Traffic source attribution:**

* Views, watch time, average view duration
* Broken by traffic source type (search, recommendations, external, etc.)

## Use cases by role

{% tabs %}
{% tab title="Content Creators" %}
Track your video performance and audience growth to understand what resonates. Pull **Video detailed statistics** with views, watch time, and engagement metrics, and break them down by day to spot trends. Use **Traffic sources** to see which discovery channels drive the most views. Monitor **Subscribers gained** by country and age to understand your audience composition.
{% endtab %}

{% tab title="Channel Managers" %}
Oversee overall channel health and team performance. Build dashboards with **Channel detailed statistics** to track views, watch time, subscribers, and engagement. Segment by content type and subscriber status using **Channel statistics by content and subscriber type** to identify which content performs best. Use **Custom reports** to combine metrics by video, device, and geography for multi-dimensional analysis.
{% endtab %}

{% tab title="Analysts & Data Teams" %}
Integrate YouTube data with other sources for cross-platform reporting. Use **Custom reports** to pull specific metrics and dimensions, then join with external data (e.g., ad spend from Google Ads) in your BI tool. Automate data refresh to BigQuery or Looker Studio for real-time dashboards. Aggregate data across multiple channels using Coupler's **Append** transformation.
{% endtab %}

{% tab title="Marketing Managers" %}
Align video performance with marketing campaigns. Pull **Video detailed statistics** to measure video ROI. Use **Subscriber growth** reports to track audience expansion. Break down views and watch time by traffic source and geography to understand which marketing channels drive discovery. Use **Join** transformations to match YouTube performance with campaign spend data.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* YouTube Analytics data is typically available within 48 hours after it's generated
* Real-time or near-real-time metrics are not available; plan accordingly when scheduling reports
* The **Subscribers gained** metric is at the channel level and cannot be filtered by video
* **Age and gender data** may show high "not specified" percentages if viewers are not logged in
* **YouTube Premium metrics** are only available if your channel is part of the YouTube Partner Program
* Some metrics (like **Annotation click-through rate**) require annotations or cards to be added to videos; if none exist, the metric will be zero
* **Live videos** are categorized as "live" in the content type dimension; on-demand videos show as "on-demand"
* Data is aggregated at the channel level in preset reports; for per-video analysis, use **Video detailed statistics** or **Custom reports**

## YouTube common issues

### Connection issues

<details>

<summary>My channel isn't showing in the channel selector</summary>

This happens when your Google account doesn't have the right access to the YouTube channel. Check the following:

1. **Sign in with the correct account** — Make sure you're signing in with a Google account that has owner or manager access to the YouTube channel. If you manage channels for clients, use their account (or have them grant you access through YouTube's sharing settings).
2. **Check YouTube access roles** — In YouTube Studio, go to Settings > Permissions to verify your account has editing rights.
3. **Reconnect the source** — Disconnect and reconnect the YouTube source in Coupler.io to refresh the channel list.
4. **Secondary channels** — If the channel is a secondary channel on your account, ensure it's linked properly in YouTube. Go to YouTube Studio > Settings > Basic info and verify the channel appears in your account.

If the channel still doesn't appear after these steps, YouTube may have a sync delay. Wait a few minutes and try reconnecting.

</details>

<details>

<summary>"Access denied" or permission error when connecting</summary>

YouTube requires specific permissions to share analytics data with Coupler.io. When you click "Sign in with Google," make sure to:

1. **Grant all requested permissions** — Don't skip or deny any permission prompts. Coupler.io needs access to YouTube Analytics data.
2. **Use the right account** — Ensure you're signed in to the Google account associated with your YouTube channel.
3. **Clear browser cache** — If you've previously denied permissions, clear your browser cookies and cache, then try connecting again.

If you're still seeing an error, your account may have restricted API access. Check YouTube's API access settings in your Google account's security dashboard.

</details>

<details>

<summary>I see "Failed to fetch channels" error</summary>

This typically indicates a temporary issue with YouTube's API. Try these steps:

1. **Wait and retry** — YouTube API can have brief outages. Wait 5-10 minutes and try connecting again.
2. **Reconnect the source** — Disconnect the YouTube source in Coupler.io and create a new connection.
3. **Check YouTube status** — Visit the Google Workspace Status Dashboard to confirm YouTube Analytics API is operational.
4. **Verify API quota** — If you have many YouTube accounts connected to Coupler.io, you may have exceeded API quota. Contact Coupler.io support if you suspect quota limits.

</details>

### Missing data

<details>

<summary>Recent data (last 2-3 days) is missing from my report</summary>

YouTube Analytics has a processing delay. Data is typically available within **48 hours** of when it's generated. This is a YouTube limitation, not a Coupler.io issue.

**If you need near-real-time data:**

* Consider using YouTube's real-time reporting in YouTube Studio for immediate insights
* Schedule Coupler.io reports to run 2+ days after the report end date to ensure data is available
* Use a date picker and manually set an end date that's 2+ days in the past if you need accurate same-day data

</details>

<details>

<summary>I'm seeing zeros for a metric I expect to have data</summary>

Some metrics only have data when certain conditions are met:

1. **Card and annotation metrics** — These only populate if you've added cards or annotations to your videos. If you haven't used these features, metrics like "Card clicks" and "Annotation click-through rate" will show zero.
2. **Premium metrics** — YouTube Premium metrics only appear if your channel is part of the YouTube Partner Program and has Premium member views.
3. **Subscriber data** — The "Subscribers gained" metric requires viewers to be logged in; unlogged viewers won't be counted.
4. **Age and gender** — These show "not specified" for a large portion of traffic if viewers aren't logged in.
5. **Traffic source detail** — Some traffic sources (e.g., "YouTube Search") only appear if traffic from that source exists in the report period.

This is expected behavior and not a data issue.

</details>

<details>

<summary>Data in Coupler.io doesn't match YouTube Studio</summary>

Small discrepancies (1-5%) are normal due to rounding and report timing. Larger differences can occur for these reasons:

1. **Report period and data processing** — YouTube Studio shows real-time estimates, while Coupler.io pulls finalized historical data. Give it 48 hours for full data availability.
2. **Dimension filtering** — If you've added dimensions (age, country, device), YouTube excludes rows with low traffic volumes (to protect viewer privacy). Coupler.io will show only the data YouTube provides.
3. **Content type classification** — Videos may be recategorized by YouTube over time. Ensure you're comparing the same date range in both places.
4. **Metric compatibility** — Some metrics are only available with certain dimension combinations. Verify your custom report isn't requesting an incompatible combination.

For large unexplained discrepancies (>10%), contact Coupler.io support with the specific metric and date range.

</details>

<details>

<summary>My video published date or video ID is missing</summary>

YouTube Analytics doesn't include video metadata like publish date, title, or duration. The **Video** dimension only includes the video title and ID, which you can use to look up additional details in YouTube Studio.

To enrich your data with publish dates:

* Use Coupler.io's **Join** transformation to combine YouTube Analytics with a custom data source containing video metadata
* Manually add a "Publish date" column in your destination and populate it with dates from YouTube Studio

</details>

### Permission errors

<details>

<summary>"You don't have permission to access this resource"</summary>

This error means your YouTube account doesn't have the required access level. Here's how to fix it:

1. **Verify ownership or manager role** — In YouTube Studio, go to Settings > Permissions. You need "Owner" or "Manager" role to share data with Coupler.io.
2. **Request access** — If you manage the channel for someone else, ask the channel owner to grant you Manager access through YouTube's sharing feature.
3. **Use the channel owner's account** — If you can't get manager access, have the channel owner sign in to Coupler.io and create the data flow themselves.

YouTube doesn't allow read-only roles (like "Moderator") to access Analytics. You must have editing rights.

</details>

### Data discrepancies

<details>

<summary>Views or watch time is higher/lower than expected in a specific report</summary>

Before investigating, confirm:

1. **Check the date range** — Make sure the report is using the correct start and end dates. Use the date picker or verify macro values (e.g., {{30daysago}}).
2. **Confirm dimension compatibility** — Some metric-dimension combinations may exclude low-traffic data. For example, if you're segmenting by age and gender, YouTube filters out rows with very small audience sizes.
3. **Verify split setting** — If you've enabled "Split data by period" (day or month), each row represents a smaller time slice. Total views will look lower in individual daily rows than in a monthly aggregate.
4. **Check additional dimensions** — If you've added extra dimensions for breakdown, traffic may be spread across many rows, making individual row values small.

If numbers still don't match YouTube Studio after confirming the above, wait 48 hours for full data processing and re-run the report.

</details>

<details>

<summary>I'm getting data type mismatch errors when writing to my destination</summary>

This happens when YouTube returns an unexpected data type that doesn't fit your destination's column. Common causes:

1. **Numeric metrics in text columns** — Metrics like views and watch time are numbers, but if your destination column is formatted as text, it may reject the data. Ensure destination columns are set to Number format.
2. **NULL or "0" values** — YouTube sometimes returns empty values for zero metrics. Ensure your destination columns allow NULL or 0 values.
3. **Large numbers exceeding limits** — If a metric exceeds your destination's column size limit, try widening the column or using a bigger numeric type (e.g., BigInt).

Fix this by:

* Checking the destination column format (should match the metric type)
* Clearing old data and re-running the flow
* Using Coupler.io's field mapping to cast columns to the correct type

</details>

### Rate limits

<details>

<summary>I'm hitting YouTube API quota limits</summary>

YouTube Analytics API has quota limits per project. If you're running many data flows from multiple channels or accounts, you may exceed your quota.

**Signs of quota exhaustion:**

* Errors like "quota exceeded" or "rate limit exceeded"
* Flows work intermittently but fail during peak times
* Multiple data flows failing simultaneously

**To resolve:**

1. **Space out scheduled runs** — If you have 5+ YouTube data flows, stagger their schedules so they don't all run at the same time. For example, run Channel A at 9 AM, Channel B at 10 AM, etc.
2. **Reduce data flow frequency** — Consider running reports daily instead of hourly, or only during low-traffic periods.
3. **Consolidate channels** — If possible, use custom reports to pull data from multiple channels in a single flow instead of creating separate flows per channel.
4. **Contact support** — If you have a legitimate business need for high-frequency reports, Coupler.io support may be able to help optimize your setup or request additional quota from Google.

YouTube API quota resets daily at midnight UTC.

</details>

<details>

<summary>Data flow fails with "Request was denied" error</summary>

This can indicate a quota or permission issue on YouTube's side. Try these steps:

1. **Verify connection is still valid** — Your YouTube auth token may have expired. Disconnect and reconnect the YouTube source in Coupler.io.
2. **Check YouTube's system status** — Visit the Google Workspace Status Dashboard to confirm YouTube Analytics API is operational.
3. **Test in YouTube Studio** — Try accessing YouTube Analytics directly in YouTube Studio to confirm the data is available and your account has access.
4. **Wait and retry** — Sometimes this is a temporary API issue. Wait 15 minutes and re-run the flow.

If the error persists, contact Coupler.io support with the exact error message and flow name.

</details>

## YouTube FAQ

<details>

<summary>Can Coupler.io pull YouTube revenue data?</summary>

YouTube's Analytics API (which Coupler.io uses) does not provide revenue, AdSense earnings, or CPM data. This data is only available directly in YouTube Studio under the "Monetization" tab or in your AdSense account.

If you need to track revenue alongside views and watch time, you can:

* Manually export revenue data from YouTube Studio or AdSense and store it in a separate sheet
* Use Coupler.io's **Join** transformation to combine YouTube performance metrics with AdSense revenue data from another source
* Use an AI destination (Claude, ChatGPT, etc.) to analyze the relationship between your content performance and earnings

If revenue reporting is critical for your business, contact Coupler.io support to discuss potential workarounds.

</details>

<details>

<summary>How often does YouTube Analytics data update in Coupler.io?</summary>

YouTube Analytics data is finalized and available within **48 hours** after it's generated. Data from "today" or "yesterday" will be incomplete. Once 48 hours have passed, data is locked in and won't change.

For scheduled flows, it's best to:

* Set the end date to 2+ days in the past (use {{60daysago}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/marketing/youtube.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
