Initiate OAuth 2.0 authentication flow.

Opens a browser window for Google OAuth consent. Required before using any tools that access private channel data or analytics.

Check current authentication status and quota usage.

Get channel details by channel ID, handle (@username), or the authenticated user's channel.

Args: channel_id: YouTube channel ID (e.g., "UCxxxxxxx") handle: Channel handle (e.g., "@mkbhd") mine: If True, get the authenticated user's own channel

List videos from a channel or playlist.

For a channel, uses the channel's uploads playlist. Returns video summaries with stats, sorted by most recent.

Args: channel_id: Channel ID to list videos from playlist_id: Playlist ID to list videos from (overrides channel_id) mine: If True, list the authenticated user's videos max_results: Number of videos to return (max 50)

Get detailed metadata and statistics for a specific video.

Args: video_id: YouTube video ID (e.g., "dQw4w9WgXcQ")

Search YouTube for videos, channels, or playlists.

Costs 100 quota units per call — use sparingly.

Args: query: Search query string search_type: Type of results: "video", "channel", or "playlist" channel_id: Limit search to a specific channel max_results: Number of results (max 50) order: Sort order: "relevance", "date", "viewCount", "rating" published_after: ISO 8601 datetime (e.g., "2025-01-01T00:00:00Z") published_before: ISO 8601 datetime region_code: ISO 3166-1 alpha-2 country code (e.g., "US")

Get YouTube autocomplete/search suggestions for a query.

Useful for SEO keyword research — shows what people are searching for. No quota cost (uses YouTube's public suggest endpoint).

Args: query: Partial search query to get suggestions for language: Language code (e.g., "en", "es")

Get currently trending videos on YouTube.

Costs 1 quota unit.

Args: region_code: ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "IN") category_id: Filter by category ID (e.g., "28" for Science & Technology) max_results: Number of videos to return (max 50)

List available YouTube video categories for a region.

Useful for filtering trending videos or setting video category on upload. Costs 1 quota unit.

Args: region_code: ISO 3166-1 alpha-2 country code (e.g., "US")

List available caption tracks for a video you own.

Requires OAuth. Only works for videos on the authenticated user's channel.

Args: video_id: YouTube video ID

Get the transcript/captions for a video.

By default uses youtube-transcript-api (works for any public video, no quota cost). Set use_official_api=True to use the official Data API (only for your own videos, costs quota units).

Args: video_id: YouTube video ID language: Preferred language code (e.g., "en", "es", "ja") use_official_api: If True, use official API (own videos only)

Get channel-level analytics summary.

Returns views, watch time, subscribers gained/lost, likes, comments, and shares for the date range.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Get top-performing videos by views.

Returns per-video metrics sorted by view count, excluding Shorts.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of videos to return (max 200).

Get top-performing Shorts by views.

Returns per-Short metrics sorted by view count.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of Shorts to return (max 200).

Get detailed analytics for a specific video over time.

Returns daily metrics for the specified video.

Args: video_id: YouTube video ID start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Get traffic source breakdown — how viewers find your content.

Shows views from search, suggested, browse, external, etc.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. video_id: Optional video ID to filter to a specific video.

Get audience demographics — age group and gender breakdown.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Get views by country.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of countries to return.

Get daily performance metrics over time.

Useful for spotting trends and finding optimal posting days. Returns one row per day with views, watch time, subs, likes, shares.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Get aggregated performance by day of week.

Fetches daily data and aggregates by weekday to show which days perform best. Useful for scheduling uploads.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 90 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Compare performance of Shorts vs long-form videos vs live streams.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Get revenue breakdown.

Requires the channel to be in the YouTube Partner Program (monetized). Returns estimated revenue, ad revenue, and YouTube Premium revenue.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Get revenue per video, sorted by highest revenue.

Requires the channel to be in the YouTube Partner Program.

Args: start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today. max_results: Number of videos to return (max 200).

Get audience retention curve for a specific video.

Returns 100 data points showing what percentage of viewers are still watching at each point in the video. Also includes relative retention compared to similar-length videos on YouTube.

Args: video_id: YouTube video ID start_date: Start date (YYYY-MM-DD). Defaults to 28 days ago. end_date: End date (YYYY-MM-DD). Defaults to today.

Upload a video to YouTube.

Costs 1,600 quota units. Video is uploaded as private by default.

Args: file_path: Absolute path to the video file title: Video title (max 100 characters) description: Video description (max 5,000 characters) tags: List of tags category_id: YouTube category ID (default "22" = People & Blogs) privacy_status: "private", "public", or "unlisted" publish_at: ISO 8601 datetime to schedule publishing (requires privacy_status="private")

Update metadata for an existing video.

Only provided fields are updated; others remain unchanged.

Args: video_id: YouTube video ID title: New title (max 100 characters) description: New description (max 5,000 characters) tags: New tags (replaces existing tags) category_id: New category ID privacy_status: "private", "public", or "unlisted"

Upload a custom thumbnail for a video.

Args: video_id: YouTube video ID file_path: Absolute path to the thumbnail image (JPEG, PNG, GIF, BMP; max 2MB)

Delete a video. This action is irreversible.

Args: video_id: YouTube video ID to delete

List playlists for a channel.

Args: channel_id: Channel ID to list playlists from mine: If True, list the authenticated user's playlists max_results: Number of playlists to return (max 50)

Create a new playlist.

Args: title: Playlist title description: Playlist description privacy_status: "private", "public", or "unlisted"

Add a video to a playlist.

Args: playlist_id: Playlist ID to add the video to video_id: Video ID to add position: Position in the playlist (0-based). Defaults to end.

Remove a video from a playlist.

Use youtube_list_playlists or the Data API to find the playlist_item_id.

Args: playlist_item_id: The playlist item ID (not the video ID)

List top-level comments on a video.

Args: video_id: YouTube video ID max_results: Number of comment threads to return (max 100) order: Sort order: "relevance" or "time"

Post a new top-level comment on a video.

Args: video_id: YouTube video ID to comment on text: Comment text

Reply to an existing comment.

Args: parent_id: The comment ID to reply to (from youtube_list_comments) text: Reply text

List available report types that can be scheduled.

Common report types:

• channel_basic_a3: User activity (views, watch time, subs)

• channel_demographics_a1: Age/gender breakdown

• channel_traffic_source_a3: Traffic sources

• channel_device_os_a3: Device and OS breakdown

• channel_combined_a3: Combined multi-dimension report

Schedule a reporting job. Reports will be generated daily.

Once created, YouTube will start generating daily CSV reports for this report type. It may take 24-48 hours for the first report to appear.

Args: report_type_id: Report type ID (from youtube_reporting_list_types) name: Optional human-readable name for the job

List all active reporting jobs.

List available reports for a job.

Reports are generated daily and available for 60 days.

Args: job_id: Job ID (from youtube_reporting_create_job or youtube_reporting_list_jobs)

Download a report CSV.

Returns the CSV content as text. For large reports, the content may be truncated.

Args: download_url: Download URL from youtube_reporting_list_reports