# YouTube tools

> The YouTube tools in the developer API, with every argument: list channels and videos, and run YouTube Analytics reports.

**Needs:** A YouTube connection (Pro and Agency). 3 tools, all read-only.

> [!IMPORTANT]
> Google is still reviewing the permission this connector needs. Until it approves it, Plugsight offers YouTube to Plugsight admins only, so for most people it isn't in the **Connector catalog** yet and these tools don't appear. See [YouTube](https://docs.plugsight.app/connectors/youtube.md).

These tools appear in `GET /v1/tools` only when the API key's MCP server includes a connection of this kind. Call each one with `POST /v1/tools/\<name>`, sending its arguments as a JSON object. See [Calling tools](https://docs.plugsight.app/developers/calling-tools.md) for the request and response format.

These tools need a plan that includes marketing connectors (Pro or Agency). On the Free plan they don't appear, even if the connection exists.

These tools don't take an `account` argument. Call `youtube_list_channels` for the channels this key reaches and pass a channel id (`UC…`) as `channel`; leave it out when there's only one. Channels you've hidden in Plugsight aren't listed and can't be read.

| Tool | What it does | Kind |
| --- | --- | --- |
| [`youtube_list_channels`](#youtube_list_channels) | List YouTube channels | Read |
| [`youtube_report`](#youtube_report) | YouTube channel report | Read |
| [`youtube_list_videos`](#youtube_list_videos) | List YouTube videos | Read |

Every tool here only reads: none of them changes anything in YouTube, so none needs `confirm`.

The example requests fill in only the required arguments, with placeholder values.

## youtube_list_channels

**List YouTube channels** · Read

The YouTube channels this MCP reaches, with subscribers, total views and video count.

No arguments: send `{}`.

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/youtube_list_channels \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## youtube_report

**YouTube channel report** · Read

YouTube Analytics for a channel over a period: views, watch time, average view duration, subscribers gained and lost, likes, comments, shares. group_by splits it: day or month (trends), video (top videos, with titles), country, device, traffic_source (search, suggested, external…), playback_location, subscribed_status, or age_gender (share of viewers). Returns a compact table with totals.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `channel` | string | No | Channel id (UC…) from youtube_list_channels (optional when there's only one) |
| `group_by` | string | No | How to split the report. One of: `none`, `day`, `month`, `video`, `country`, `device`, `traffic_source`, `playback_location`, `subscribed_status`, `age_gender`. Default `"none"`. |
| `metrics` | array of string | No | YouTube Analytics metrics. Default: views, estimatedMinutesWatched, averageViewDuration, subscribersGained, subscribersLost, likes, comments, shares. Traffic, device and location splits allow views and estimatedMinutesWatched |
| `sort_by` | string | No | Metric to rank by, for video, country and source splits. Default: the first metric |
| `limit` | integer | No | Most rows to return. From 1 to 200. Default `25`. |
| `date_preset` | string | No | Used when date_from/date_to aren't given. Default last_28d. One of: `last_7d`, `last_28d`, `last_30d`, `last_90d`, `last_365d`, `this_month`, `last_month`, `this_year`, `last_year`. |
| `date_from` | string | No | YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo") |
| `date_to` | string | No | YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo") |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/youtube_report \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## youtube_list_videos

**List YouTube videos** · Read

A channel's uploads, newest first, with publish date, length, views, likes, comments and link. Use youtube_report with group_by video for watch time over a period.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `channel` | string | No | Channel id (UC…) from youtube_list_channels (optional when there's only one) |
| `search` | string | No | Only videos whose title contains this |
| `limit` | integer | No | Most videos to return. From 1 to 200. Default `25`. |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/youtube_list_videos \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Related articles

- [YouTube](https://docs.plugsight.app/connectors/youtube.md)
- [Calling tools](https://docs.plugsight.app/developers/calling-tools.md)
- [Errors](https://docs.plugsight.app/developers/errors.md)
- [Accounts tools](https://docs.plugsight.app/developers/accounts-tools.md)

---

Web version: https://docs.plugsight.app/developers/youtube-tools
