> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruby.ad/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube Analytics

> Report on your channel's views, watch time, audience, retention and revenue, and download bulk reports.

![YouTube](https://mintcdn.com/ruby-ai/LyGmDUG1gNsMgHcI/branding/integrations/youtube.svg?fit=max\&auto=format\&n=LyGmDUG1gNsMgHcI\&q=85\&s=cd99b47f095f44e074c159a525b0a86a)

> [!NOTE]
>
> YouTube tools are in preview and enabled per workspace. If a tool is missing, use your Ruby support channel to request access.

Let agents compare channel performance over time, find top videos, understand where viewers come from and where they stop watching, and report on revenue.

## Connect

1. As a workspace admin, go to **Spaces → Tools** and add **YouTube Analytics**.
2. Choose Personal or Workspace authentication, click **Connect**, and sign in with the Google account that manages your channel.
3. Review Google's requested access to channel information, analytics and monetary reports, then complete the connection.
4. Add YouTube Analytics to the agents that need it. With Personal authentication, each user connects their own Google account when prompted.

This is a separate connection from YouTube and YouTube Live. See [YouTube setup](https://docs.ruby.ad/docs/user-documentation/agents/tools/youtube#connect) for the authentication options.

## Tools

| Tool | Description | Asks before running |
| - | - | - |
| Get YouTube analytics overview | Get the YouTube channel's key performance numbers for a period (views, engaged views, watch time, average view duration, subscribers gained and lost, likes, comments, shares), compared with the previous period of the same length. | Runs automatically |
| Query YouTube Analytics | Run a custom YouTube Analytics report for the channel with any supported metrics, dimensions, filters and sort (e.g. views by day for a video, watch time by country, traffic source details). | Runs automatically |
| Get top YouTube videos | Get the YouTube channel's top videos (or top Shorts or live streams) for a period, ranked by views, watch time, likes, comments, shares or subscribers gained. | Runs automatically |
| Get YouTube audience breakdown | Break down YouTube channel or video performance for a period by day, month, country, viewer age and gender, device, operating system, traffic source, playback location, subscribed status, sharing service or content type (Shorts, videos, live). | Runs automatically |
| Get YouTube video retention | Get the audience retention curve of a YouTube video: the share of viewers still watching at each point of the video, compared with similar videos. | Runs automatically |
| Get YouTube revenue report | Get the YouTube channel's estimated revenue, ad revenue, gross revenue, CPM, playback-based CPM, monetized playbacks and ad impressions for a period, in total or by day, month, country or video. Needs a channel in the YouTube Partner Program. | Runs automatically |
| List YouTube Analytics groups | List the YouTube Analytics groups (custom collections of videos, playlists or channels used to aggregate analytics) of the channel. | Runs automatically |
| List YouTube Analytics group items | List the videos, playlists or channels in a YouTube Analytics group. | Runs automatically |
| List YouTube report types | List the YouTube Reporting API bulk report types (daily CSV exports) available for the channel. | Runs automatically |
| List YouTube reporting jobs | List the YouTube Reporting API jobs scheduled for the channel, which generate a bulk CSV report every day. | Runs automatically |
| Create YouTube reporting job | Schedule a YouTube Reporting API job that generates a bulk CSV report of a given type every day. The first report is available within 24 hours. | Asks once |
| Delete YouTube reporting job | Delete a YouTube Reporting API job so it stops generating bulk reports. | Asks once |
| List YouTube bulk reports | List the daily bulk CSV reports generated by a YouTube Reporting API job (kept by YouTube for 60 days). | Runs automatically |
| Download YouTube bulk report | Download one YouTube bulk report into the conversation as a CSV export. | Runs automatically |

## Ask for a report

Give the agent a date range and the breakdown you want. For example:

* Compare this month's views, watch time and subscribers with the previous month.
* Find our top Shorts by watch time and break down their traffic sources.
* Show the audience retention curve for a video.
* Download the latest bulk report as a CSV file.

Analytics data can lag by about two days. Revenue reports require a channel in the YouTube Partner Program, and revenue figures are estimates.

Bulk reporting jobs produce daily CSV files. The first report can take up to 24 hours, and YouTube keeps generated reports for 60 days. Creating a reporting job does not immediately create a downloadable report.

## Asks before running

The tables show the default approvals. Your workspace's tool settings can change when approval is required.

| Value | Meaning |
| - | - |
| Runs automatically | The agent reads data without asking. |
| Asks once | The agent asks the first time. You can approve the action for good. |
| Asks every time | The agent asks you to approve each use. |

Connecting your Google account grants access to YouTube. Approving a tool action in chat is a separate step: review the proposed content and changes before approving. You can reject the action instead.

Reports and downloads run automatically. Creating or deleting a daily bulk reporting job asks once by default. Deleting a job stops it from generating future reports; this tool does not publish or edit videos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.