Skip to main content

YouTube

List the connected channel's uploads, fetch a single video's details, and pull YouTube Analytics metrics for a video over a date range — a fully read-only family.

Every tool on this page requires a YouTube connector (see Connectors); pass its ID as connectorId. Listing reads the channel's uploads playlist via the YouTube Data API, and the analytics tool queries the YouTube Analytics API. The connector stores the channel's metadata (channel ID and uploads playlist) at authorization time — if a tool fails with MISSING_METADATA, reconnect the YouTube account.

Get videos TOOLYOUTUBE_GET_VIDEOS​

Lists videos from the connected channel's uploads playlist, newest first. maxResults defaults to 25 and caps at 50; page further by passing the nextPageToken from a previous response as pageToken. Set minimal to true to trim each video to videoId, title, and description — useful when an agent only needs to pick a video. The response also carries the channel's channelId and channelTitle.

Example​

Tool config
{
  "toolType": "YOUTUBE_GET_VIDEOS",
  "connectorId": "V1StGXR8Z5",
  "maxResults": 25,
  "minimal": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the YouTube connection References a connector by ID.
  • Name
    maxResults
    Type
    integer
    Description
    Maximum number of videos to return (default 25, max 50)
  • Name
    pageToken
    Type
    string
    Description
    Page token for pagination from previous response
  • Name
    minimal
    Type
    boolean
    Description
    When true, returns minimal video info (videoId, title, description only)

Get video by ID TOOLYOUTUBE_GET_VIDEO_BY_ID​

Fetches one video's full details by its YouTube videoId — the same ID that appears in the video's URL and in the list tool's results. Use it to inspect a specific video without paging through the uploads playlist.

Example​

Tool config
{
  "toolType": "YOUTUBE_GET_VIDEO_BY_ID",
  "connectorId": "V1StGXR8Z5",
  "videoId": "@@{VIDEO_ID}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the YouTube connection References a connector by ID.
  • Name
    videoId
    Type
    string
    Description
    The YouTube video ID to retrieve

Get video analytics TOOLYOUTUBE_GET_VIDEO_ANALYTICS​

Runs a YouTube Analytics report for one video over startDate to endDate (both YYYY-MM-DD; defaults to the last 30 days), returning views, estimated minutes watched, average view duration and percentage, likes, dislikes, comments, shares, and subscribers gained. Set includeTrafficSources to true to add a views and watch-time breakdown by traffic source. Analytics need the channel metadata stored on the connector, and freshly published videos can lag a day or two behind in YouTube's reporting.

Example​

Tool config
{
  "toolType": "YOUTUBE_GET_VIDEO_ANALYTICS",
  "connectorId": "V1StGXR8Z5",
  "videoId": "@@{VIDEO_ID}",
  "startDate": "2026-06-01",
  "endDate": "2026-06-30",
  "includeTrafficSources": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the YouTube connection References a connector by ID.
  • Name
    videoId
    Type
    string
    Description
    The YouTube video ID to get analytics for
  • Name
    startDate
    Type
    string
    Description
    Start date in YYYY-MM-DD format (default: 30 days ago)
  • Name
    endDate
    Type
    string
    Description
    End date in YYYY-MM-DD format (default: today)
  • Name
    includeTrafficSources
    Type
    boolean
    Description
    Whether to include traffic source breakdown