Skip to main content

YouTube Analytics

This connector syncs data from YouTube into your destination using Google OAuth. It supports multiple YouTube APIs to extract different kinds of data:

  • YouTube Data API (v3) for metadata (for example, channels, videos, playlists).
  • YouTube Reporting API for bulk downloadable reports (job-based).
  • YouTube Analytics API (Query API) for analytics reports (metrics/dimensions over a date range).
info

API Documentation:

Source Setup Guide​

Step 1​

Click banner in the Edit Source form.

Step 2​

Follow the authentication flow (OAuth) on Google/YouTube to grant Extract the required permissions.

Step 3​

Confirm you can see your email and profile picture, and that the source is Connected.

note

The API Client uses YouTube API Services.

By authorizing this connector, you agree to:

You can revoke access on the Google Security Settings page.

Step 4 (optional): Content Owner ID (for Content Owner reports)​

If you are a YouTube Content Owner (MCN / CMS account), add your Content Owner ID. This enables syncing content owner reports from the Reporting API.

To retrieve all content owner IDs associated with your admin account:

  1. Visit the Content Owner endpoint docs:
    https://developers.google.com/youtube/partner/reference/rest/v1/contentOwners/list?apix_params=%7B%22fetchMine%22%3Atrue%7D
  2. In the API Explorer, set fetchMine to true and click Execute.
  3. Sign in with the relevant Google admin account and accept prompts.
  4. The response includes content owner names and their corresponding IDs.

Connection Setup Guide​

Once you connect YouTube to a destination, configure:

  • Connection Pull Schedule: how frequently data is extracted.
  • Backfill (Days): how much historical data is retrieved on each run.
  • Destination-specific settings: e.g., dataset name / schema / warehouse options.
  • Schema Migration Policy: how schema changes are handled.

Authentication​

This connector uses Google OAuth 2.0. You authenticate by signing in to Google and granting access.

If you use Content Owner features, you may also provide:

  • Content Owner ID (on_behalf_of_content_owner)

Configuration fields​

Source-level fields commonly used by this connector:

FieldRequiredDescription
client_idYesGoogle OAuth client ID.
client_secretYesGoogle OAuth client secret.
tokenYesOAuth refresh token (created during the OAuth flow).
on_behalf_of_content_ownerNoContent Owner ID used for Content Owner Reporting API reports.

Some streams also define stream-specific configuration in connector_specific (for example, Analytics Query API reports). These are managed by the connector and typically don’t need manual editing unless instructed.

Configuration​

Configure the YouTube source by setting the required authentication and selecting which YouTube Analytics API mode you want to use.

This connector uses OAuth. During setup you’ll be prompted to authorize access to the YouTube account.

Choose an API mode​

The connector can extract analytics data using either:

  • YouTube Reporting API (pre-generated reports)
  • YouTube Analytics Query API (custom queries)

Which one you use determines which configuration fields are required.

YouTube Analytics Query API configuration​

Use this mode when you want to define your own query (dimensions/metrics/filters).

  • ids (string, required)
    The ids parameter for the Analytics Query API. Common values include:

    • channel==MINE to query the authenticated user’s channel
    • channel==<CHANNEL_ID> to query a specific channel

  • dimensions (string[], required)
    One or more dimensions to group results by (for example, day, country, video, playlist).

  • metrics (string[], required)
    One or more metrics to return (for example, views, estimatedMinutesWatched, averageViewDuration).

  • filters (string, optional)
    A static filter expression passed through to the Analytics Query API (for example, country==US).

  • sort (string or string[], optional)
    Sort order for the query. You can provide a single string (for example, -views) or an array of sort fields (for example, ["-views","day"]). If an array is provided, it will be joined with commas.

  • max_results (number, optional)
    Page size for the Analytics Query API. Values are clamped to the API’s supported range (1–200). If not set, the connector uses 200.

Dynamic filter batching (optional)​

Some dimensions (for example, playlists) can be expensive or error-prone to query in a single request when many IDs are involved. To help with this, the connector supports building and executing the query as a series of smaller filtered requests.

  • dynamic_filter_dimension (string, optional)
    If set, the connector will enumerate values for this dimension and run the analytics query in batches using a generated filter for each batch.

  • dynamic_filter_batch_size (number, optional)
    The number of values to include per generated filter batch. Values are clamped to 1–200.

If a batched request fails due to transient/internal errors, the connector may retry and further split batches to complete extraction.

YouTube Reporting API configuration​

Use this mode when you want to pull from pre-generated YouTube Reporting reports. Configure the report/job selection fields as prompted in the UI (the connector will create or reuse a reporting job and then download the report data for extraction).

Schema ERD​

Explore the interactive entity relationship diagram for Youtube.

Open page

Data Streams​

The connector can expose multiple stream types (metadata, reporting, analytics). Stream availability depends on your YouTube account permissions and whether you provided a Content Owner ID.

Analytics (Query API) streams​

These streams are powered by the YouTube Analytics Query API and are typically date-ranged (respecting your connection backfill window).

  • channel_demographics
  • channel_device_os_daily
  • channel_geography_country
  • channel_geography_province
  • channel_playback_location_daily
  • channel_time_daily
  • channel_traffic_source_daily
  • playlist_device_os
  • playlist_geography_country
  • playlist_playback_location
  • playlist_time_daily
  • playlist_traffic_source
  • video_geography_country
  • video_time_daily
  • video_traffic_source

Notes on Analytics Query API behavior​

  • Analytics queries are executed over a start date / end date derived from your connection schedule and backfill.
  • Some analytics reports may be scoped to:
    • the authenticated user’s channel (ids=channel==MINE), and/or
    • specific channels (when applicable), and/or
    • filtered entities (for example, videos or playlists) depending on the report design.
  • The YouTube Analytics API enforces quotas and per-request limits; the connector may paginate and/or batch requests to stay within API constraints.

Reporting API streams (job-based)​

If enabled for your account, the connector can also sync Reporting API reports (bulk downloadable reports). These are created and fetched via jobs and may require Content Owner access for content owner reports.

Metadata (YouTube Data API v3) streams​

The connector can also sync metadata via the YouTube Data API (v3), such as channel/video/playlist metadata, depending on the configured catalog.

Connector Information​

  • Connector name: YouTube
  • APIs used: YouTube Data API (v3), YouTube Analytics API, YouTube Reporting API
  • Auth: OAuth 2.0 (Google)

Notes​

  • YouTube Analytics API can return intermittent internalError responses. The connector automatically retries these requests.

  • If you use dynamic playlist filtering, the Analytics API may still return internalError for some playlist batches even after retries. In that case, the connector will automatically split the playlist batch into smaller batches and retry until it succeeds or the batch can no longer be split. This behavior is automatic and does not require any configuration changes.

Troubleshooting​

403: The request is not properly authorized to retrieve YouTube Analytics data​

This typically means the authenticated Google account doesn’t have access to the channel (or the channel isn’t linked to the correct YouTube/Google account).

  • Confirm you authenticated with the Google account that owns (or is a manager of) the YouTube channel.
  • If you’re querying a CMS/Content Owner, confirm the account has the appropriate YouTube Analytics access.
  • Re-authenticate the connector after permissions are corrected.

400: Invalid value '...': Unknown identifier​

This usually indicates an invalid dimensions, metrics, or filters combination for the YouTube Analytics Query API.

  • Verify the requested dimensions/metrics are supported together for the report you’re running.
  • If you use filters, confirm the filter syntax matches the YouTube Analytics API format (for example, video==VIDEO_ID).
  • If you recently changed configuration, re-run after reverting to a known-good combination.

500: internalError when using playlist filters​

YouTube Analytics can intermittently return internalError for requests that filter on many playlists at once (for example, when batching playlist IDs in a filter).

The connector will automatically retry these requests. If the error persists, it will fall back to splitting the playlist batch into smaller requests and retrying, which can increase runtime.

If you continue to see repeated internalError failures:

  • Reduce the number of playlist IDs included in a single run (for example, narrow the scope of the report).
  • Re-run later; these errors are often transient on Google’s side.

Slow runs / rate limiting​

YouTube APIs enforce quotas and rate limits. If your run is slow or appears to stall:

  • Reduce the number of dimensions/metrics requested per report.
  • Reduce the overall scope (fewer channels, fewer filters).
  • Re-run during off-peak hours.

If the connector fails with repeated HTTP 429 or quota-related errors, wait and retry after the quota window resets.