Skip to main content

YouTube Data API

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Connector type (beta)
Available Data replicationNot available Agent(learn more)
Support Level
Airbyte
Connector Version
1.0.7 (last updated 10 days ago)
Sync Success Rate
High
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
743a2a44-fd13-4109-a8fe-fb0e68f467f5

This page contains the setup guide and reference information for the YouTube Data API source connector.

This connector uses the YouTube Data API v3 to sync data about your YouTube channels, including video details, channel metadata, and comments. For more detailed analytics and reporting data, use the YouTube Analytics connector.

Prerequisites​

  • One or more YouTube Channel IDs you want to sync data from
  • (For Airbyte Open Source) A Google Cloud project with the YouTube Data API v3 enabled, and one of the following authentication methods from that project:
    • A Google API Key (public data only)
    • OAuth 2.0 credentials (Client ID, Client Secret, and Refresh Token)

Setup guide​

Find your YouTube Channel IDs​

  1. Go to YouTube and navigate to the channel you want to sync.
  2. The Channel ID is in the URL: https://www.youtube.com/channel/CHANNEL_ID. Channel IDs are 24 characters long and start with UC. A handle URL such as https://www.youtube.com/@handle isn't a Channel ID.
  3. Alternatively, you can find it in YouTube Studio under Settings > Channel > Advanced settings.

The connector fails the connection check if any Channel ID doesn't resolve to an existing channel, so verify each ID before you set up the source.

For Airbyte Cloud​

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. Select YouTube Data API from the list.
  4. Enter a name for your source.
  5. Choose your authentication method:
    • For OAuth 2.0: Click Sign in with Google to authenticate your Google account.
    • For API Key: Enter your Google API key.
  6. Enter one or more Channel IDs to sync data from.
  7. Click Set up source.

For Airbyte Open Source​

Create credentials​

You can authenticate using either an API Key or OAuth 2.0.

Option A: API Key (simpler setup, public data only)

  1. Go to the Google Cloud Console.
  2. Create a new project or select an existing one.
  3. Navigate to APIs & Services > Library and enable the YouTube Data API v3.
  4. Go to APIs & Services > Credentials.
  5. Click Create Credentials > API key.
  6. Copy the generated API key.
  7. (Recommended) Click Restrict key to limit the key's usage to the YouTube Data API v3.

Option B: OAuth 2.0 (required for accessing private data)

  1. Go to the Google Cloud Console.
  2. Create a new project or select an existing one.
  3. Navigate to APIs & Services > Library and enable the YouTube Data API v3.
  4. Go to APIs & Services > Credentials.
  5. Click Create Credentials > OAuth client ID. Configure the OAuth consent screen if prompted.
  6. Select Web application as the application type, and add https://developers.google.com/oauthplayground as an authorized redirect URI so you can generate a refresh token in the next steps.
  7. Copy the Client ID and Client Secret.
  8. Open the OAuth 2.0 Playground. Click the settings icon, select Use your own OAuth credentials, and enter your Client ID and Client Secret.
  9. In the scope field, enter https://www.googleapis.com/auth/youtube.force-ssl, then click Authorize APIs. Sign in with the Google account that owns the channel if you want to sync unlisted and private videos.
  10. Click Exchange authorization code for tokens and copy the Refresh token.

If your OAuth consent screen's publishing status is Testing, Google expires refresh tokens after 7 days, and syncs start failing with authentication errors. Set the publishing status to In production before you generate the refresh token you use for scheduled syncs.

Set up the connector​

  1. In Airbyte, go to Sources and click + New source.
  2. Select YouTube Data API from the list.
  3. Enter a name for your source.
  4. Choose your authentication method and enter the required credentials.
  5. Enter one or more Channel IDs to sync data from.
  6. Click Set up source.

Supported sync modes​

The YouTube Data API source connector supports the following sync modes:

Every stream except channels supports incremental sync. The YouTube Data API has no date filters, but every endpoint the connector reads lists newest first, so an incremental sync reads pages until it reaches the first record it already has and stops. See Quota and rate limiting for the request cost of each stream.

Two streams behave differently in incremental mode:

  • video only fetches videos published since the last sync. Its statistics fields are a snapshot from the moment the video was first fetched and are not refreshed; use video_engagement for counters that move.
  • video_engagement re-reads the counters of every video on every sync and stamps each record with the fetch time as its cursor. Incremental - Append therefore builds a time series of counters per video, while Incremental - Append + Deduped keeps only the latest counters.

The comment streams use the top-level comment's publish time as the cursor, so incremental syncs don't pick up edits to existing comments or changes to their reply counts. Incremental syncs also don't remove videos or comments that were deleted on YouTube from the destination.

Supported streams​

Stream NamePrimary KeyCursorPaginationSupports Full SyncSupports Incremental
videosvideoIdpublishedAtDefaultPaginatorYesYes
videovideoIdpublishedAtDefaultPaginatorYesYes
video_engagementvideoIddatetime (fetch time)NoneYesYes
channelsid—DefaultPaginatorYesNo
commentsvideoId, idpublishedAtDefaultPaginatorYesYes
channel_commentschannelId, idpublishedAtDefaultPaginatorYesYes

Stream descriptions​

  • videos: One record per upload in each configured channel. For each channel returned by the channels stream, this stream reads the channel's uploads playlist with playlistItems.list, 50 items per page. Records are thin: kind and videoId (primary key) from the playlist item's resourceId, channelId, title, publishedAt (when the upload was added to the channel), and privacyStatus (public, unlisted, or private). With OAuth 2.0 as the channel owner this includes unlisted and private uploads; with an API key, or for channels the OAuth user doesn't own, only public uploads. The video, video_engagement, and comments streams use this stream as their parent to identify which videos to fetch.
  • video: Detailed information about videos from the specified channels, from videos.list, fetched 50 videos per request. Data includes snippet information (title, description, thumbnails, publish date, tags, category, language settings), content details (duration, dimension, definition, caption availability, region restrictions), statistics (view count, like count, comment count), player information (embed HTML), and status (upload status, privacy status, license, embeddable, made for kids). Each record also includes a datetime field that the connector sets to the time it fetched the record. It isn't a YouTube timestamp; use it to tell snapshots apart in Full Refresh - Append mode.
  • video_engagement: The current statistics of every video from the specified channels (viewCount, likeCount, commentCount, favoriteCount), from videos.list with part=statistics, 50 videos per request, plus videoId and a datetime field set to the fetch time. YouTube exposes only cumulative counters, not history, so each sync is one snapshot; schedule the connection at the cadence you want the series sampled. For daily views, watch time, and other report metrics use the YouTube Analytics connector.
  • channels: Information about the specified YouTube channels, from channels.list. Data includes snippet information (title, description, custom URL, country, thumbnails), content details (related playlists), statistics (subscriber count, view count, video count), branding settings (channel keywords, trailer, default language), topic details (topic categories), status (privacy status, made for kids), localizations, and content owner details. The connector also adds an uploadsPlaylistId field, copied from contentDetails.relatedPlaylists.uploads, which the videos stream uses to list the channel's uploads.
  • comments: Comment threads on individual videos from the specified channels, from commentThreads.list filtered by videoId. For each video discovered by the videos stream, this stream fetches the comment threads, newest first, 100 per request. Each record is one thread's snippet: the top-level comment is in topLevelComment, totalReplyCount gives the number of replies, and the connector copies the top-level comment's ID into a top-level id field (part of the primary key) and its publishedAt into a top-level publishedAt field (the cursor). The replies themselves aren't included in the records. Videos with comments disabled and videos that no longer exist are skipped without failing the sync.
  • channel_comments: All comment threads related to the specified channels, from commentThreads.list filtered by allThreadsRelatedToChannelId, newest first, 100 per request. This includes comments on the channel's videos and on the channel page itself, so it provides a broader view of channel engagement than the comments stream, and an incremental sync costs one or two requests per channel instead of one per video. Records have the same shape as comments, including the copied id and publishedAt fields. If you don't need comments partitioned by video, prefer this stream over comments.

Comment records also carry updatedAt inside the nested topLevelComment.snippet object; it isn't hoisted to the top level and isn't used as a cursor.

YouTube API Services usage disclosure​

This connector uses YouTube API Services to retrieve data from YouTube. By using this connector, you agree to be bound by the YouTube Terms of Service.

YouTube API Services are provided by Google. For information about how Google handles data, review the Google Privacy Policy.

When using OAuth 2.0 authentication, this connector accesses authorized user data. You can revoke the connector's access to your Google account at any time through the Google security settings page. To delete stored data that was previously synced, remove the relevant connection in your Airbyte workspace or delete the data from your configured destination.

Limitations and considerations​

Quota and rate limiting​

The YouTube Data API enforces a daily quota per Google Cloud project. Google's documented default allocation is 10,000 quota units per day, and every endpoint this connector reads (playlistItems.list, channels.list, videos.list, and commentThreads.list) costs 1 unit per request. Google notes that defaults are subject to change, so check the Quotas page for the YouTube Data API in the Google Cloud console to see what applies to your project. If you need more, request a quota extension from Google.

Requests per sync scale with the number of videos, V, in the configured channels. The video, video_engagement, and comments streams each read the uploads playlist themselves to find video IDs, so their costs below include that parent read. video reads only new playlist items in incremental mode, while video_engagement and comments re-read the whole playlist on every sync.

StreamFirst sync or Full RefreshIncremental sync
videosAbout V/50About one per channel
videoAbout V/50 for the playlist plus V/50 for video detailsAbout one per channel, plus one per 50 new videos
video_engagementAbout V/50 for the playlist plus V/50 for statisticsSame as a first sync
channelsOne per channelNot supported
commentsAbout V/50 for the playlist, plus one per video, plus one per additional 100 comment threads on a videoAbout V/50 for the playlist plus one per video
channel_commentsOne per channel, plus one per additional 100 comment threadsAbout one or two per channel

For example, a 5,000-video channel syncing videos, video, video_engagement, channels, and channel_comments incrementally every hour uses roughly 200 units per sync, or about 5,000 per day. Most of that is video_engagement; sync it less often, or not at all, if you don't need frequent counter snapshots.

The connector also paces its own requests as a burst guard: at most 100 requests per minute across all endpoints. A request that would exceed this limit waits for the next free slot rather than failing. If YouTube returns a per-minute rate-limit error (rateLimitExceeded, userRateLimitExceeded, or HTTP 429), the connector retries with backoff. If YouTube reports the daily quota as exhausted (quotaExceeded or dailyLimitExceeded), the sync fails immediately rather than retrying, because the quota only resets at midnight Pacific time; incremental streams resume from their last checkpoint on the next scheduled sync.

The connector's pacing applies to each Airbyte source separately, but Google meters quota per Google Cloud project. If several sources use API keys or OAuth clients from the same project, their requests add up against one quota. Use a separate project for each source, or request more quota.

Authentication​

  • API keys can only access public data. To sync unlisted and private videos, and comments on them, you must use OAuth 2.0 authentication as the owner of the channel.
  • When using OAuth 2.0, the connector requests the youtube.force-ssl scope, which provides read and write access to YouTube resources. This scope is required even though the connector only reads data.
  • When using OAuth 2.0, the connector refreshes the access token and retries if YouTube returns HTTP 401. If the 401 persists, the sync fails with a configuration error; re-authenticate with Google from the source settings. With an API key there's no token to refresh, so a persistent 401 fails the same way.
  • The connector fails with a configuration error, rather than retrying, when YouTube reports that the API key is invalid, the token lacks the youtube.force-ssl scope, the YouTube Data API v3 isn't enabled for the project, or a configured Channel ID doesn't exist. Fix the credentials or Channel IDs and run the sync again.
  • The connector does not support service account authentication because the YouTube Data API does not support this method for most operations.

Data coverage​

  • The videos stream reads each channel's uploads playlist, which has no result cap, so it returns every upload regardless of channel size.
  • Unlisted and private uploads appear in videos, video, video_engagement, and comments only when the source authenticates with OAuth 2.0 as the channel owner. With an API key, or for channels the OAuth user doesn't own, these streams contain public videos only.
  • YouTube exposes only current engagement counters. video_engagement records are per-sync snapshots, not a history the connector can backfill.
  • The comments stream skips videos with comments disabled and deleted videos without producing records or errors.
  • Incremental comments keeps a cursor per video. On channels with more than 10,000 videos the connector switches to a single cursor for the stream, which can re-read more comments per sync than strictly necessary.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
array
channel_ids
object
credentials

Changelog​

Expand to review
VersionDatePull RequestSubject
1.1.02026-10-2087495Add incremental sync to videos, video, comments, and channel_comments; add the video_engagement stream; add publishedAt, privacyStatus, channelId, and title to videos records; fetch 50 videos per videos.list request and 100 comment threads per commentThreads.list request; fail fast when the daily quota is exhausted
1.0.82026-10-2089482Update dependencies
1.0.72026-10-1388831Update dependencies
1.0.62026-10-0787637Enumerate channel videos through the uploads playlist to remove the search endpoint's 500-video cap.
1.0.52026-10-0688113Update dependencies
1.0.42026-09-2987429Update dependencies
1.0.32026-09-2286891Update dependencies
1.0.22026-09-2186466Fix authentication failures (HTTP 401) on channels with many videos: refresh the access token and retry on 401, and shorten API budget windows so syncs no longer wait past the token lifetime
1.0.12026-09-1586306Update dependencies
1.0.02026-09-1085214Breaking: promote connector to certified — declare primary keys and timestamp formats and restrict videos to video results (see the migration guide)
0.0.662026-09-0885721Update dependencies
0.0.652026-08-1884813Update dependencies
0.0.642026-08-1184181Update dependencies
0.0.632026-08-0483693Update dependencies
0.0.622026-07-2883186Update dependencies
0.0.612026-07-2182663Update dependencies
0.0.602026-07-1482070Update dependencies
0.0.592026-06-3081317Update dependencies
0.0.582026-06-2380730Update dependencies
0.0.572026-06-1680123Update dependencies
0.0.562026-06-0979580Update dependencies
0.0.552026-06-0279000Update dependencies
0.0.542026-04-2877496Update dependencies
0.0.532026-04-2176818Update dependencies
0.0.522026-04-0875185Replace connector icon with updated YouTube logo
0.0.512026-03-1774392Migrate to scopes object array format
0.0.502026-03-1774698Update dependencies
0.0.492026-03-0373914Update dependencies
0.0.482026-02-1773507Update dependencies
0.0.472026-02-1073175Update dependencies
0.0.462026-01-2772066Update dependencies
0.0.452026-01-1470677Update dependencies
0.0.442026-01-0571016Fixed schemas
0.0.432025-12-1970971Add acceptance tests
0.0.422025-12-1669315Add OAuth 2.0 support
0.0.412025-11-2570079Update dependencies
0.0.402025-11-1869532Update dependencies
0.0.392025-10-2968942Update dependencies
0.0.382025-10-2168456Update dependencies
0.0.372025-10-1467987Update dependencies
0.0.362025-10-0767241Update dependencies
0.0.352025-09-3066846Update dependencies
0.0.342025-09-2466475Update dependencies
0.0.332025-09-0965731Update dependencies
0.0.322025-08-2465468Update dependencies
0.0.312025-08-1064863Update dependencies
0.0.302025-08-0264386Update dependencies
0.0.292025-07-2664056Update dependencies
0.0.282025-07-1963640Update dependencies
0.0.272025-07-1263216Update dependencies
0.0.262025-07-0562701Update dependencies
0.0.252025-06-2862233Update dependencies
0.0.242025-06-2161759Update dependencies
0.0.232025-06-1561171Update dependencies
0.0.222025-05-2460786Update dependencies
0.0.212025-05-1059968Update dependencies
0.0.202025-05-0459566Update dependencies
0.0.192025-04-2658930Update dependencies
0.0.182025-04-1958550Update dependencies
0.0.172025-04-1358052Update dependencies
0.0.162025-04-0557379Update dependencies
0.0.152025-03-2956821Update dependencies
0.0.142025-03-2256338Update dependencies
0.0.132025-03-0955664Update dependencies
0.0.122025-03-0155162Update dependencies
0.0.112025-02-2354632Update dependencies
0.0.102025-02-1553087Update dependencies
0.0.92025-01-2552387Update dependencies
0.0.82025-01-1852006Update dependencies
0.0.72025-01-1151380Update dependencies
0.0.62025-01-0450753Update dependencies
0.0.52024-12-2150326Update dependencies
0.0.42024-12-1449756Update dependencies
0.0.32024-12-1249403Update dependencies
0.0.22024-12-1149125Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
0.0.12024-11-08Initial release by @bala-ceg via Connector Builder
Was this page helpful?