YouTube is the world’s largest video-sharing platform, enabling users to upload, view, and share video content. The YouTube Data API and Analytics API provide access to channel statistics, video metrics, playlists, member information, comments, and detailed performance analytics, making it valuable for content creators and businesses to analyze their video performance and audience engagement.

Configuring YouTube as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the YouTube option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

You’ll need to authorize Nekt to connect to YouTube. You can do this by clicking the Google Authorization button. During the authorization process, you’ll be prompted to select which YouTube account to connect:

Personal Account: Your main YouTube account linked directly to your Google account
Brand Account: A separate YouTube channel managed through your Google account (commonly used for businesses, organizations, or creators who want to keep their channel separate from their personal account)

Make sure to select the correct account that owns the channel you want to extract data from. If you manage multiple Brand Accounts, you’ll see a list of all available channels to choose from.

The Comment Threads and Comment Replies streams need the “Manage your YouTube account” permission, which Google only grants during authorization. If your YouTube source was authorized before this permission was offered, open the source, run the Google Authorization again and accept it; until then those two streams are skipped with a warning in the run log, and every other stream keeps syncing normally.

Once you authorize your account, add the following information:

Channel ID: The YouTube channel ID to sync data from. You can find it by Clicking your channel avatar in the top-right corner > Settings > Advanced Settings > Channel ID (check this link for more details).
Start Date (Optional): The earliest record date to sync. This helps filter historical data if you don’t need all historical records. For comments, this bounds the work: threads are returned newest first, and pagination stops at the first page whose threads were last active before this date.
Livestream reports lookback (days) (Optional): How many days back the livestream report streams (concurrent viewers, audience retention and traffic sources) look for broadcasts. Each broadcast in the window costs one request per stream on every sync, so lower this on channels with a long streaming history and raise it only to backfill older broadcasts. (Default: 365)

Click Next.

2. Select streams

Choose which data streams you want to sync: you can select all streams or pick specific ones that matter most to you. The available streams include: Core Data Streams:

Channels, Comment Threads, Comment Replies, Members, Playlists, Playlist Items, Video Categories, Videos

Analytics Reports:

Report Channel Daily Stats
Report Video Daily Stats
Report Playlist Daily Stats
Report Channel Stats by Age and Gender
Report Channel Stats by Country
Report Channel Stats by OS and Device
Report Livestream Concurrent Viewers
Report Livestream Audience Retention
Report Livestream Traffic Sources

Tip: The stream can be found more easily by typing its name.

Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
- Incremental: every time the extraction happens, we’ll get only the new data, which is good if, for example, you want to keep every record ever fetched.
- Full table: every time the extraction happens, we’ll get the current state of the data, which is good if, for example, you don’t want to have deleted data in your catalog.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:

Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

For you to be able to see it on your Catalog, you need at least one successful source run.

Streams and Fields

Below you’ll find all available data streams from YouTube and their corresponding fields:

Core Data Streams

Channels

Stream containing detailed information about YouTube channels, including statistics, branding, and content details.Fields:

Field	Type	Description
`id`	String	The channel’s unique system ID
`kind`	String	The type of the API resource
`etag`	String	The ETag of the resource
`pageInfo`	Object	Pagination information
`pageInfo.totalResults`	Integer	Total number of results
`pageInfo.resultsPerPage`	Integer	Number of results per page
`snippet`	Object	Basic channel information
`snippet.title`	String	The channel’s title
`snippet.description`	String	The channel’s description
`snippet.customUrl`	String	The channel’s custom URL
`snippet.publishedAt`	DateTime	When the channel was created
`snippet.thumbnails`	Object	Channel thumbnail images in various sizes (default, medium, high)
`snippet.defaultLanguage`	String	The channel’s default language
`snippet.localized`	Object	Localized channel title and description
`snippet.country`	String	Country associated with the channel
`statistics`	Object	Channel performance metrics
`statistics.viewCount`	Integer	Total number of channel views
`statistics.subscriberCount`	Integer	Number of subscribers
`statistics.hiddenSubscriberCount`	Boolean	Whether subscriber count is hidden
`statistics.videoCount`	Integer	Number of videos uploaded
`contentDetails`	Object	Content-related information
`contentDetails.relatedPlaylists`	Object	IDs of related playlists (likes, favorites, uploads, watchHistory, watchLater)
`status`	Object	Channel status information
`status.privacyStatus`	String	The channel’s privacy status
`status.isLinked`	Boolean	Whether linked to a Google+ account
`status.longUploadsStatus`	String	Whether the channel can create long uploads
`status.madeForKids`	Boolean	Whether the channel is designated as child-directed
`status.selfDeclaredMadeForKids`	Boolean	Self-declaration of child-directed content
`brandingSettings`	Object	Channel branding configuration
`brandingSettings.channel`	Object	Channel settings (title, description, keywords, tracking, moderation settings)
`brandingSettings.image`	Object	Banner images in various formats (mobile, tablet, TV, desktop)

Comment Threads

One row per top-level comment on any of the channel’s videos, plus comments left on the channel itself. Read channel-wide through commentThreads.list (100 threads per request), newest first.

Requires the “Manage your YouTube account” permission on the authorization. Only comments with moderation status published are returned; the moderation queue is not extracted.

Fields:

Field	Type	Description
`id`	String	ID YouTube uses to uniquely identify the comment thread; equals the ID of its top-level comment
`kind`	String	The type of the API resource (value: ‘youtube#commentThread’)
`etag`	String	The ETag of the resource
`snippet`	Object	Details about the thread and its top-level comment
`snippet.channelId`	String	ID of the channel the thread belongs to
`snippet.videoId`	String	ID of the video the thread is on; absent when the comment was left on the channel itself
`snippet.postId`	String	ID of the community post the thread is on, if any
`snippet.canReply`	Boolean	Whether the authorized account can reply to the thread
`snippet.totalReplyCount`	Integer	Total number of replies to the top-level comment (the replies themselves are in Comment Replies)
`snippet.isPublic`	Boolean	Whether the thread, and therefore all its comments, is visible to all YouTube users
`snippet.topLevelComment`	Object	The top-level comment that opens the thread
`snippet.topLevelComment.id`	String	ID of the top-level comment (same as the thread ID)
`snippet.topLevelComment.kind`	String	The type of the API resource (value: ‘youtube#comment’)
`snippet.topLevelComment.etag`	String	The ETag of the comment resource
`snippet.topLevelComment.snippet`	Object	Details of the top-level comment (same fields as a reply’s `snippet`, listed below)
`snippet.topLevelComment.snippet.channelId`	String	ID of the YouTube channel the comment refers to (for a video comment, the channel that uploaded the video)
`snippet.topLevelComment.snippet.videoId`	String	ID of the video the comment was posted on; absent for comments left on the channel itself
`snippet.topLevelComment.snippet.postId`	String	ID of the community post the comment was left on, if any
`snippet.topLevelComment.snippet.parentId`	String	ID of the top-level comment a reply belongs to; only set on replies
`snippet.topLevelComment.snippet.textDisplay`	String	The comment’s text as displayed on YouTube, in plain text
`snippet.topLevelComment.snippet.textOriginal`	String	The comment’s original raw text as posted or last edited (returned when accessible to the authorized account, which is guaranteed for the channel owner)
`snippet.topLevelComment.snippet.authorDisplayName`	String	Display name of the user who posted the comment
`snippet.topLevelComment.snippet.authorProfileImageUrl`	String	URL of the author’s avatar
`snippet.topLevelComment.snippet.authorChannelUrl`	String	URL of the author’s YouTube channel, if any
`snippet.topLevelComment.snippet.authorChannelId`	Object	Channel of the comment author
`snippet.topLevelComment.snippet.authorChannelId.value`	String	ID of the author’s YouTube channel
`snippet.topLevelComment.snippet.canRate`	Boolean	Whether the authorized account can rate (like) this comment
`snippet.topLevelComment.snippet.viewerRating`	String	Rating the authorized account gave this comment: `none` or `like`
`snippet.topLevelComment.snippet.likeCount`	Integer	Total number of likes the comment has received
`snippet.topLevelComment.snippet.moderationStatus`	String	Moderation status on the channel owner’s side: `published`, `heldForReview`, `likelySpam` or `rejected`
`snippet.topLevelComment.snippet.publishedAt`	DateTime	When the comment was originally published
`snippet.topLevelComment.snippet.updatedAt`	DateTime	When the comment was last edited (equals `publishedAt` when never edited)

Comment Replies

One row per reply to a top-level comment. Child of Comment Threads: replies already included in the thread response are used directly; when a thread has more replies than the response carries, the full list is fetched with comments.list.

Requires the “Manage your YouTube account” permission on the authorization.

Fields:

Field	Type	Description
`id`	String	ID YouTube uses to uniquely identify the reply
`kind`	String	The type of the API resource (value: ‘youtube#comment’)
`etag`	String	The ETag of the resource
`thread_id`	String	ID of the comment thread (top-level comment) this reply belongs to; joins to Comment Threads `id`
`video_id`	String	ID of the video the thread is on, taken from the parent thread; absent for channel-level threads
`snippet`	Object	Details of the reply
`snippet.channelId`	String	ID of the YouTube channel the comment refers to (for a video comment, the channel that uploaded the video)
`snippet.videoId`	String	ID of the video the comment was posted on; absent for comments left on the channel itself
`snippet.postId`	String	ID of the community post the comment was left on, if any
`snippet.parentId`	String	ID of the top-level comment a reply belongs to; only set on replies
`snippet.textDisplay`	String	The comment’s text as displayed on YouTube, in plain text
`snippet.textOriginal`	String	The comment’s original raw text as posted or last edited (returned when accessible to the authorized account, which is guaranteed for the channel owner)
`snippet.authorDisplayName`	String	Display name of the user who posted the comment
`snippet.authorProfileImageUrl`	String	URL of the author’s avatar
`snippet.authorChannelUrl`	String	URL of the author’s YouTube channel, if any
`snippet.authorChannelId`	Object	Channel of the comment author
`snippet.authorChannelId.value`	String	ID of the author’s YouTube channel
`snippet.canRate`	Boolean	Whether the authorized account can rate (like) this comment
`snippet.viewerRating`	String	Rating the authorized account gave this comment: `none` or `like`
`snippet.likeCount`	Integer	Total number of likes the comment has received
`snippet.moderationStatus`	String	Moderation status on the channel owner’s side: `published`, `heldForReview`, `likelySpam` or `rejected`
`snippet.publishedAt`	DateTime	When the comment was originally published
`snippet.updatedAt`	DateTime	When the comment was last edited (equals `publishedAt` when never edited)

Members

Stream for accessing YouTube channel membership information.

Note that this endpoint requires special permissions and can only be used by individual creators for their own channel-memberships-enabled YouTube channel.

Fields:

Field	Type	Description
`id`	String	The unique ID of the member resource
`kind`	String	Identifies the API resource’s type (value: ‘youtube#member’)
`etag`	String	The ETag of the resource
`snippet`	Object	Member information
`snippet.creatorChannelId`	String	The YouTube channel ID of the creator who owns the membership
`snippet.memberDetails`	Object	Object containing member channel information
`snippet.memberDetails.channelId`	String	The YouTube channel ID of the member
`snippet.memberDetails.channelUrl`	String	The URL of the member’s YouTube channel
`snippet.memberDetails.displayName`	String	The display name of the member
`snippet.memberDetails.profileImageUrl`	String	The URL of the member’s profile image
`snippet.membershipsDetails`	Object	Object describing membership details
`snippet.membershipsDetails.highestAccessibleLevel`	String	The ID of the highest accessible membership level
`snippet.membershipsDetails.highestAccessibleLevelDisplayName`	String	Display name of the highest accessible level
`snippet.membershipsDetails.accessibleLevels`	Array	List of accessible membership level IDs
`snippet.membershipsDetails.membershipsDuration`	Object	Total duration information
`snippet.membershipsDetails.membershipsDuration.memberSince`	DateTime	When the user’s membership started
`snippet.membershipsDetails.membershipsDuration.memberTotalDurationMonths`	Integer	Total duration in months
`snippet.membershipsDetails.membershipsDurationAtLevel`	Array	Duration at each membership level

Playlists

Stream containing information about playlists in the YouTube channel.Fields:

Field	Type	Description
`id`	String	The playlist’s unique system ID
`kind`	String	The type of the API resource
`etag`	String	The ETag of the resource
`snippet`	Object	Basic playlist information
`snippet.publishedAt`	DateTime	When the playlist was created
`snippet.channelId`	String	The ID of the channel that owns the playlist
`snippet.title`	String	The playlist’s title
`snippet.description`	String	The playlist’s description
`snippet.thumbnails`	Object	Playlist thumbnail images in various sizes (default, medium, high, standard, maxres)
`snippet.channelTitle`	String	The channel title
`snippet.defaultLanguage`	String	The playlist’s default language
`snippet.localized`	Object	Localized playlist title and description
`status`	Object	Playlist status information
`status.privacyStatus`	String	The playlist’s privacy status
`contentDetails`	Object	Content information
`contentDetails.itemCount`	Integer	The number of videos in the playlist
`player`	Object	Player information
`player.embedHtml`	String	An iframe tag that embeds a player that will play the playlist

Playlist Items

Stream for managing individual items (videos) within playlists. This stream is a child of the Playlists stream.Fields:

Field	Type	Description
`id`	String	The playlist item’s unique system ID
`playlist_id`	String	Playlist ID from parent context
`kind`	String	The type of the API resource
`etag`	String	The ETag of the resource
`snippet`	Object	Basic item information
`snippet.publishedAt`	DateTime	When the item was added to the playlist
`snippet.channelId`	String	The ID of the channel that owns the playlist
`snippet.title`	String	The item’s title
`snippet.description`	String	The item’s description
`snippet.thumbnails`	Object	Item thumbnail images in various sizes (default, medium, high, standard, maxres)
`snippet.channelTitle`	String	The channel title
`snippet.playlistId`	String	The ID of the playlist that contains the item
`snippet.position`	Integer	The order in which the item appears in the playlist
`snippet.resourceId`	Object	Resource information
`snippet.resourceId.kind`	String	The type of the resource
`snippet.resourceId.videoId`	String	The ID that YouTube uses to uniquely identify the video
`snippet.videoOwnerChannelTitle`	String	The title of the video owner’s channel
`snippet.videoOwnerChannelId`	String	The ID of the video owner’s channel
`contentDetails`	Object	Content information
`contentDetails.videoId`	String	The ID that YouTube uses to uniquely identify the video
`contentDetails.startAt`	Integer	When the video should start playing (in seconds)
`contentDetails.endAt`	Integer	When the video should stop playing (in seconds)
`contentDetails.note`	String	A user-generated note for this item
`contentDetails.videoPublishedAt`	DateTime	When the video was published
`status`	Object	Item status information
`status.privacyStatus`	String	The playlist item’s privacy status

Video Categories

Stream containing available YouTube video categories. By default, this retrieves categories for the US region.Fields:

Field	Type	Description
`id`	String	The category’s unique system ID
`kind`	String	The type of the API resource
`etag`	String	The ETag of the resource
`snippet`	Object	Category information
`snippet.channelId`	String	The channel ID
`snippet.title`	String	The category’s title
`snippet.assignable`	Boolean	Whether videos can be assigned to this category

Videos

Stream providing comprehensive information about individual videos from the channel. This stream is a child of the Channels stream.Fields:

Field	Type	Description
`id`	String	The video’s unique system ID
`kind`	String	The type of the API resource
`etag`	String	The ETag of the resource
`snippet`	Object	Basic video details
`snippet.publishedAt`	DateTime	When the video was published
`snippet.channelId`	String	ID of the channel that published the video
`snippet.title`	String	Video title
`snippet.description`	String	Description of the video
`snippet.thumbnails`	Object	Video thumbnail images in various sizes (default, medium, high, standard, maxres)
`snippet.channelTitle`	String	Title of the channel
`snippet.categoryId`	String	Category ID for the video
`snippet.liveBroadcastContent`	String	Indicates if the video is a live broadcast
`snippet.defaultLanguage`	String	The video’s default language
`snippet.localized`	Object	Localized versions of the video’s metadata
`snippet.defaultAudioLanguage`	String	Default audio language
`contentDetails`	Object	Detailed content information
`contentDetails.duration`	String	The duration of the video (ISO 8601 format)
`contentDetails.dimension`	String	2D or 3D video
`contentDetails.definition`	String	Video definition (hd, sd, etc)
`contentDetails.caption`	Boolean	Indicates if captions are available
`contentDetails.licensedContent`	Boolean	Whether the video is licensed content
`contentDetails.contentRating`	Object	Ratings that apply to the video
`contentDetails.projection`	String	Projection type of the video
`status`	Object	Status details
`status.uploadStatus`	String	Upload status
`status.privacyStatus`	String	Privacy status
`status.license`	String	License of the video
`status.embeddable`	Boolean	If the video is embeddable
`status.publicStatsViewable`	Boolean	If public stats are viewable
`status.madeForKids`	Boolean	Whether the video is made for kids
`statistics`	Object	Video performance metrics
`statistics.viewCount`	Integer	Number of views
`statistics.likeCount`	Integer	Number of likes
`statistics.favoriteCount`	Integer	Number of favorites
`statistics.commentCount`	Integer	Number of comments
`liveStreamingDetails`	Object	Metadata about a live broadcast, present only when the video is an upcoming, live or completed broadcast
`liveStreamingDetails.actualStartTime`	DateTime	The time the broadcast actually started
`liveStreamingDetails.actualEndTime`	DateTime	The time the broadcast actually ended
`liveStreamingDetails.scheduledStartTime`	DateTime	The time the broadcast is scheduled to begin
`liveStreamingDetails.scheduledEndTime`	DateTime	The time the broadcast is scheduled to end
`liveStreamingDetails.concurrentViewers`	Integer	The number of viewers watching the broadcast at the moment this record was extracted
`liveStreamingDetails.activeLiveChatId`	String	The ID of the live chat currently attached to the broadcast
`player`	Object	Player information
`player.embedHtml`	String	Embed HTML for the video
`topicDetails`	Object	Topic information
`topicDetails.topicCategories`	Array	List of topic categories
`localizations`	Object	Localized metadata for the video, keyed by language code
`paidProductPlacementDetails`	Object	Paid product placement information
`paidProductPlacementDetails.hasPaidProductPlacement`	Boolean	If the video has paid product placement

Analytics Reports

These streams provide detailed analytics data from the YouTube Analytics API, enabling deep insights into channel, video, and playlist performance.

Report Channel Daily Stats

Daily aggregated statistics for the entire channel. This stream provides a comprehensive view of channel performance over time.Fields:

Field	Type	Description
`day`	String	Date of the metrics (YYYY-MM-DD format)
`views`	Integer	Number of times the channel’s videos were viewed
`estimatedMinutesWatched`	Integer	Total watch time in minutes
`averageViewDuration`	Integer	Average view duration in seconds
`averageViewPercentage`	Number	Average percentage of video watched
`engagedViews`	Integer	Views where the user watched at least 30 seconds
`subscribersGained`	Integer	New subscribers gained
`subscribersLost`	Integer	Subscribers lost
`likes`	Integer	Number of likes
`dislikes`	Integer	Number of dislikes
`comments`	Integer	Number of comments
`shares`	Integer	Number of shares
`videosAddedToPlaylists`	Integer	Videos added to playlists
`videosRemovedFromPlaylists`	Integer	Videos removed from playlists
`redViews`	Integer	Views from YouTube Premium members
`estimatedRedMinutesWatched`	Integer	Watch time from YouTube Premium members
`cardImpressions`	Integer	Number of card impressions
`cardClicks`	Integer	Number of card clicks
`cardClickRate`	Number	Click-through rate for cards
`cardTeaserImpressions`	Integer	Card teaser impressions
`cardTeaserClicks`	Integer	Card teaser clicks
`cardTeaserClickRate`	Number	Click-through rate for card teasers
`annotationImpressions`	Integer	Annotation impressions
`annotationClickableImpressions`	Integer	Clickable annotation impressions
`annotationClicks`	Integer	Annotation clicks
`annotationClickThroughRate`	Number	Annotation click-through rate
`annotationClosableImpressions`	Integer	Closable annotation impressions
`annotationCloses`	Integer	Annotation closes
`annotationCloseRate`	Number	Annotation close rate

Report Video Daily Stats

Daily statistics for each video in the channel. This stream is a child of the Videos stream, providing granular performance data per video.Fields:

Field	Type	Description
`video_id`	String	The ID of the video
`video_title`	String	The title of the video
`day`	String	Date of the metrics (YYYY-MM-DD format)
`views`	Integer	Number of times the video was viewed
`estimatedMinutesWatched`	Integer	Total watch time in minutes
`averageViewDuration`	Integer	Average view duration in seconds
`averageViewPercentage`	Number	Average percentage of video watched
`engagedViews`	Integer	Views where the user watched at least 30 seconds
`subscribersGained`	Integer	New subscribers gained
`subscribersLost`	Integer	Subscribers lost
`likes`	Integer	Number of likes
`dislikes`	Integer	Number of dislikes
`comments`	Integer	Number of comments
`shares`	Integer	Number of shares
`videosAddedToPlaylists`	Integer	Videos added to playlists
`videosRemovedFromPlaylists`	Integer	Videos removed from playlists
`redViews`	Integer	Views from YouTube Premium members
`estimatedRedMinutesWatched`	Integer	Watch time from YouTube Premium members
`cardImpressions`	Integer	Number of card impressions
`cardClicks`	Integer	Number of card clicks
`cardClickRate`	Number	Click-through rate for cards
`cardTeaserImpressions`	Integer	Card teaser impressions
`cardTeaserClicks`	Integer	Card teaser clicks
`cardTeaserClickRate`	Number	Click-through rate for card teasers
`annotationImpressions`	Integer	Annotation impressions
`annotationClickableImpressions`	Integer	Clickable annotation impressions
`annotationClicks`	Integer	Annotation clicks
`annotationClickThroughRate`	Number	Annotation click-through rate
`annotationClosableImpressions`	Integer	Closable annotation impressions
`annotationCloses`	Integer	Annotation closes
`annotationCloseRate`	Number	Annotation close rate

Report Playlist Daily Stats

Daily statistics for each playlist in the channel. This stream is a child of the Playlists stream.Fields:

Field	Type	Description
`playlist_id`	String	The ID of the playlist
`playlist_title`	String	The title of the playlist
`day`	String	Date of the metrics (YYYY-MM-DD format)
`playlistStarts`	Integer	Number of times viewers started watching the playlist
`playlistViews`	Integer	Number of video views within the playlist
`playlistEstimatedMinutesWatched`	Integer	Total watch time in the playlist
`playlistAverageViewDuration`	Integer	Average view duration within the playlist
`playlistSaves`	Integer	Number of times the playlist was saved
`viewsPerPlaylistStart`	Number	Average number of video views per playlist start
`averageTimeInPlaylist`	Integer	Average time spent watching the playlist

Report Channel Stats by Age and Gender

Audience demographics breakdown showing the age and gender distribution of viewers.Fields:

Field	Type	Description
`ageGroup`	String	Age bracket (e.g., age13-17, age18-24, age25-34, age35-44, age45-54, age55-64, age65-)
`gender`	String	Viewer gender (male, female)
`viewerPercentage`	Number	Percentage of views from this demographic segment

Report Channel Stats by Country

Geographic breakdown of channel performance by country.Fields:

Field	Type	Description
`country`	String	ISO 3166-1 alpha-2 country code
`views`	Integer	Number of views from this country
`estimatedMinutesWatched`	Integer	Total watch time from this country
`engagedViews`	Integer	Engaged views from this country
`averageViewDuration`	Integer	Average view duration
`averageViewPercentage`	Number	Average percentage of video watched
`likes`	Integer	Number of likes
`dislikes`	Integer	Number of dislikes
`comments`	Integer	Number of comments
`shares`	Integer	Number of shares
`subscribersGained`	Integer	New subscribers from this country
`subscribersLost`	Integer	Subscribers lost from this country

Report Channel Stats by OS and Device

Device and operating system breakdown showing how viewers access your content.Fields:

Field	Type	Description
`operatingSystem`	String	Operating system (e.g., ANDROID, IOS, WINDOWS, LINUX, MACINTOSH)
`deviceType`	String	Device type (e.g., MOBILE, TABLET, DESKTOP, TV, GAME_CONSOLE)
`views`	Integer	Number of views from this device/OS combination
`estimatedMinutesWatched`	Integer	Total watch time
`engagedViews`	Integer	Engaged views
`averageViewDuration`	Integer	Average view duration
`averageViewPercentage`	Number	Average percentage of video watched

Report Livestream Concurrent Viewers

Concurrent viewers of a livestream, one row per minute of the broadcast. This stream is a child of the Videos stream.Fields:

Field	Type	Description
`video_id`	String	The ID of the video that was broadcast live
`video_title`	String	The title of the video that was broadcast live
`livestreamPosition`	Integer	Position within the livestream that the row describes, as the number of seconds elapsed since the broadcast started
`averageConcurrentViewers`	Integer	The average number of viewers watching the broadcast simultaneously during this minute
`peakConcurrentViewers`	Integer	The peak number of viewers watching the broadcast simultaneously during this minute

Report Livestream Audience Retention

Audience retention of a livestream, including how many viewers joined and left. This stream is a child of the Videos stream.Fields:

Field	Type	Description
`video_id`	String	The ID of the video that was broadcast live
`video_title`	String	The title of the video that was broadcast live
`elapsedVideoTimeRatio`	Number	The portion of the video that the row describes, as a ratio between 0 and 1 of the video’s total length
`elapsedVideoTimePercent`	Integer	The same portion of the video expressed as a whole percentage from 1 to 100
`audienceWatchRatio`	Number	The absolute ratio of viewers watching the video at this point
`relativeRetentionPerformance`	Number	How well the video retains viewers during this portion relative to other YouTube videos of a similar length
`startedWatching`	Integer	How often viewers started watching the video during this portion of it
`stoppedWatching`	Integer	How often viewers stopped watching the video during this portion of it
`totalSegmentImpressions`	Integer	How often this portion of the video was viewed

Report Livestream Traffic Sources

How viewers reached a livestream, split between the broadcast and its replay. This stream is a child of the Videos stream.Fields:

Field	Type	Description
`video_id`	String	The ID of the video that was broadcast live
`video_title`	String	The title of the video that was broadcast live
`insightTrafficSourceType`	String	How viewers reached the video (e.g., NOTIFICATION, SUBSCRIBER, EXT_URL, IMMERSIVE_LIVE)
`liveOrOnDemand`	String	Whether the views happened while the broadcast was live (LIVE) or on the recording afterwards (ON_DEMAND)
`views`	Integer	The number of views that came from this traffic source
`estimatedMinutesWatched`	Integer	The estimated number of minutes that viewers from this traffic source watched

Data Model

The following diagram illustrates the relationships between the data streams. Analytics report streams are linked to their parent entities.

Implementation Notes

Analytics API vs Data API

This connector uses two YouTube APIs:

YouTube Data API v3: For core data (Channels, Videos, Playlists, Members, Video Categories, Comment Threads, Comment Replies)
YouTube Analytics API: For detailed reporting streams (all “Report” streams)

Analytics data may have a delay of 24-48 hours compared to real-time statistics shown in YouTube Studio.

Comments: permission, coverage and quota

Permission: commentThreads.list and comments.list are the only read endpoints of the YouTube Data API that reject the read-only permission; they need “Manage your YouTube account” (youtube.force-ssl). A source authorized before that permission was offered gets a warning in the run log and the two comment streams are skipped, without affecting the other streams. Re-run the Google Authorization on the source to enable them.
Coverage: comments are read channel-wide, for every video of the channel and for the channel itself, newest first. Only comments with moderation status published are included. Comments that were deleted or removed by moderation disappear from the tables on the next full sync.
Start Date: the API has no date filter, so the connector reads threads newest first and stops at the first page whose threads were last active before the Start Date. A thread published before the Start Date is still included when it received a reply after it.
Quota: every request costs one unit of the YouTube Data API daily quota. A run costs roughly one unit per 100 comment threads, plus one unit for each thread with more than five replies. On channels with a very large comment history, set a more recent Start Date to keep runs light.

Incremental Sync

The following streams support incremental sync using the day dimension as the replication key:

Report Channel Daily Stats
Report Video Daily Stats
Report Playlist Daily Stats

Demographics streams (Age & Gender, Country, OS & Device) provide aggregated totals for the channel and sync in full table mode. Livestream report streams (Concurrent Viewers, Audience Retention, Traffic Sources) also sync in full table mode for a rolling window defined by your lookback configuration. Comment Threads and Comment Replies sync in full table mode so that like counts, edits and deleted comments stay current; the Start Date bounds how far back comments are read.

Parent-Child Relationships

Some streams are children of other streams:

Report Video Daily Stats → requires Videos stream (syncs stats per video)
Report Playlist Daily Stats → requires Playlists stream (syncs stats per playlist)
Playlist Items → requires Playlists stream (syncs items per playlist)
Report Livestream Concurrent Viewers → requires Videos stream (syncs data per livestream)
Report Livestream Audience Retention → requires Videos stream (syncs data per livestream)
Report Livestream Traffic Sources → requires Videos stream (syncs data per livestream)
Comment Replies → requires Comment Threads stream (syncs replies per thread)

When selecting a child stream, the parent stream will be automatically included.

API Quirks and Pagination

The YouTube API exhibits specific behaviors that the connector automatically handles:

Circular Pagination: The Playlist Items and Comment Threads APIs can sometimes loop over previously seen page tokens (e.g., A → B → … → A). The connector detects these cycles and safely terminates pagination to prevent infinite loops and duplicate records.
Deduplication: When extracting video IDs for channels, the connector automatically removes duplicates while preserving the correct order, guarding against content shifting across different API page tokens.

Skills for agents

Download YouTube skills file

YouTube connector documentation as plain markdown, for use in AI agent contexts.

Get started

Context

Activate

Organizations

Workspaces

Resources

YouTube as a data source

Configuring YouTube as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Core Data Streams

Analytics Reports

Data Model

Implementation Notes

Skills for agents

Download YouTube skills file

​Configuring YouTube as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​Streams and Fields

​Core Data Streams

​Analytics Reports

​Data Model

​Implementation Notes

​Skills for agents

Download YouTube skills file

Configuring YouTube as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Core Data Streams

Analytics Reports

Data Model

Implementation Notes

Skills for agents