YouTube Analytics API Source
This guide explains how to configure the YouTube Analytics API as a data source in Mage. Learn how to authenticate with Google Cloud, request the necessary OAuth scopes, and sync data from specific channels.
Try our fully managed solution to access this advanced feature.
Mage supports ingesting data from YouTube Analytics by connecting to the YouTube Analytics API and YouTube Data API v3 using OAuth 2.0 credentials.
This integration allows you to extract rich channel analytics, video performance, and viewer engagement metrics directly into your Mage pipelines.
🔧 Configuration
To connect to the YouTube Analytics API, provide the following parameters in your source configuration:
| Key | Description | Sample Value | Required |
|---|---|---|---|
client_id | OAuth 2.0 Client ID from Google Cloud Console | 123456789-abcdef.apps.googleusercontent.com | ✅ |
client_secret | OAuth 2.0 Client Secret from Google Cloud Console | abcdefghijklmnopqrstuvwxyz | ✅ |
refresh_token | OAuth 2.0 refresh token for authenticating requests | 1//abcdefghijklmnopqrstuvwxyz | ✅ |
start_date | Start date for pulling analytics data | 2021-01-01T00:00:00Z | ✅ |
user_agent | User agent string identifying the integration | example@example.com | ✅ |
channel_ids | Comma-separated list of channel IDs to retrieve analytics for | UC1234..., UC5678... | ✅ |
🔐 How to Generate Credentials
Follow these steps to generate the required credentials from the Google Cloud Console:
1. Set Up OAuth Credentials
- Go to Google Cloud Console
- Create a new project (or use an existing one)
- Enable the following APIs:
- YouTube Data API v3
- YouTube Analytics API v2
- Navigate to “APIs & Services > Credentials”
- Create a new OAuth 2.0 Client ID (select “Web application” or “Desktop app”)
2. Generate a Refresh Token
Use OAuth 2.0 Playground to get a refresh_token:
- Click the gear icon and check “Use your own OAuth credentials”, then enter your Client ID and Secret.
- Select the following scopes:
https://www.googleapis.com/auth/youtube.readonlyhttps://www.googleapis.com/auth/yt-analytics.readonly
- Follow the steps to authorize, exchange code for tokens, and copy the refresh token.
How It Works
This integration connects to two key Google APIs to extract YouTube Analytics data and video metadata:
APIs Used
-
YouTube Reporting API
Used to retrieve bulk analytics reports for YouTube channels and content owners.- Jobs: List available report jobs
- Reports: Retrieve generated reports
- Report Types: View available report categories
- Report examples:
-
YouTube Data API v3
Used to fetch real-time metadata and performance metrics for channels, videos, and playlists.
Supported Streams
The following streams are available in the YouTube Analytics integration:
| Stream | Description |
|---|---|
channels | Metadata and statistics for authenticated YouTube channels |
playlist_items | Videos and items within playlists |
playlists | Metadata about playlists created by the authenticated user |
reports | Bulk analytics data from YouTube Reporting API |
videos | Video metadata, engagement, and performance statistics |
Sync Behavior
-
Incremental Syncs
The integration supports stateful incremental loading, so only new or modified records are fetched during each sync run. -
Schema Output
Mage automatically generates the output schema for each stream, making it easier to understand and work with the resulting data.