youtube-kit

by eukosh

Overview Schema Source Related Servers Discussions Admin

Python

Local

Get Analytics

get_analytics

Read-onlyIdempotent

YouTube Analytics for your channel: totals, or rows broken down by one dimension.

Instructions

YouTube Analytics for your channel: totals, or rows broken down by one dimension.

Data for the last two or three days is incomplete, so recent rows keep growing. Uses the separate YouTube Analytics API and its quota; enable it in the same Google Cloud project.

Quota: no YouTube Data API units.

Input Schema

Name	Required	Description
`by`	No	Break the numbers down by this dimension; its column is named as given here. Omit for totals. By month, the range widens to whole months. By elapsed: the audience retention of exactly one video, a row per 1% of its length (0.01 to 1). By traffic-source-detail, which needs traffic_source: the search terms behind YT_SEARCH, the videos behind RELATED_VIDEO, the sites behind EXT_URL.
`sort`	No	Metric or dimension to sort by; prefix with - for descending, e.g. -views. Defaults to chronological by day, month or elapsed, and to the first metric, descending, by anything else.
`limit`	No	Maximum number of rows. Breaking down by video returns at most 200, 25 by default; by traffic-source-detail, at most 25. Other breakdowns return every row by default.
`since`	No	First day, inclusive: 2026-01-01, or 90d / 4w before until. Defaults to 28 days before until.
`until`	No	Last day, inclusive: 2026-01-31, or 7d / 1w ago. Defaults to today.
`videos`	No	Only these videos (IDs or URLs).
`country`	No	Only viewers in this country, e.g. US. Not by elapsed.
`metrics`	No	Metric names from https://developers.google.com/youtube/analytics/metrics, e.g. views, estimatedMinutesWatched, subscribersGained. Defaults to views, watch time, average view duration, likes, comments, and subscribers gained and lost. By device, os, traffic-source, playback-location or subscribed, only watch metrics work (views, estimatedMinutesWatched, averageViewDuration, averageViewPercentage), and those are the default. By age or gender, only viewerPercentage works. By elapsed: audienceWatchRatio (share of viewers watching at that point, above 1 with rewatches) and relativeRetentionPerformance (0 to 1, against videos of similar length) by default, or startedWatching and stoppedWatching. By traffic-source-detail: views and estimatedMinutesWatched. By sharing-service: shares.
`my_channel`	No	Which of your logged-in channels to work on: UC… ID, @handle or exact title. Omit for the default channel.
`content_type`	No	Only long-form videos (videoOnDemand), shorts, or live streams (liveStream), as the content-type breakdown names them. Not by elapsed.
`traffic_source`	No	The source to break down by traffic-source-detail, as the traffic-source breakdown names it, e.g. YT_SEARCH. Only with that breakdown.

Output Schema

Name	Required	Description
`rows`	Yes
`since`	Yes
`until`	Yes
`columns`	Yes	Dimension first (if any), then the metrics, in request order.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.7.1Oct 22, 2026

changedInput schema / properties / by / anyOf

Previous value: -[
-  {
-    "enum": [
-      "day",
-      "month",
-      "video",
-      "country",
-      "device",
-      "os",
-      "traffic-source",
-      "playback-location",
-      "age",
-      "gender",
-      "subscribed"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "day",
+      "month",
+      "video",
+      "country",
+      "device",
+      "os",
+      "traffic-source",
+      "traffic-source-detail",
+      "playback-location",
+      "age",
+      "gender",
+      "subscribed",
+      "content-type",
+      "sharing-service",
+      "elapsed"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / by / description

Previous value: -"Break the numbers down by this dimension; its column is named as given here. Omit for totals.\nBy month, the range widens to whole months."New value: +"Break the numbers down by this dimension; its column is named as given here. Omit for totals.\nBy month, the range widens to whole months. By elapsed: the audience retention of exactly one\nvideo, a row per 1% of its length (0.01 to 1). By traffic-source-detail, which needs\ntraffic_source: the search terms behind YT_SEARCH, the videos behind RELATED_VIDEO, the sites\nbehind EXT_URL."

addedInput schema / properties / content_type

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "videoOnDemand",
+        "shorts",
+        "liveStream"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only long-form videos (videoOnDemand), shorts, or live streams (liveStream), as the\ncontent-type breakdown names them. Not by elapsed."
+}

addedInput schema / properties / country

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only viewers in this country, e.g. US. Not by elapsed."
+}

changedInput schema / properties / limit / description

Previous value: -"Maximum number of rows. Breaking down by video returns at most 200, 25 by default;\nother breakdowns return every row by default."New value: +"Maximum number of rows. Breaking down by video returns at most 200, 25 by default; by\ntraffic-source-detail, at most 25. Other breakdowns return every row by default."

changedInput schema / properties / metrics / description

Previous value: -"Metric names from https://developers.google.com/youtube/analytics/metrics, e.g. views,\nestimatedMinutesWatched, subscribersGained. Defaults to views, watch time, average view\nduration, likes, comments, and subscribers gained and lost. By device, os, traffic-source,\nplayback-location or subscribed, only watch metrics work (views, estimatedMinutesWatched,\naverageViewDuration, averageViewPercentage), and those are the default. By age or gender,\nonly viewerPercentage works."New value: +"Metric names from https://developers.google.com/youtube/analytics/metrics, e.g. views,\nestimatedMinutesWatched, subscribersGained. Defaults to views, watch time, average view\nduration, likes, comments, and subscribers gained and lost. By device, os, traffic-source,\nplayback-location or subscribed, only watch metrics work (views, estimatedMinutesWatched,\naverageViewDuration, averageViewPercentage), and those are the default. By age or gender,\nonly viewerPercentage works. By elapsed: audienceWatchRatio (share of viewers watching at that\npoint, above 1 with rewatches) and relativeRetentionPerformance (0 to 1, against videos of\nsimilar length) by default, or startedWatching and stoppedWatching. By traffic-source-detail:\nviews and estimatedMinutesWatched. By sharing-service: shares."

changedInput schema / properties / sort / description

Previous value: -"Metric or dimension to sort by; prefix with - for descending, e.g. -views. Defaults to\nchronological by day or month, and to the first metric, descending, by anything else."New value: +"Metric or dimension to sort by; prefix with - for descending, e.g. -views. Defaults to\nchronological by day, month or elapsed, and to the first metric, descending, by anything else."

addedInput schema / properties / traffic_source

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The source to break down by traffic-source-detail, as the traffic-source breakdown names\nit, e.g. YT_SEARCH. Only with that breakdown."
+}

First observedv0.1.0Oct 18, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/openWorld, so the description adds real operational context: two-to-three-day data lag, a separate quota pool that consumes no Data API units, and an enablement prerequisite. That is exactly the kind of non-schema behavior an agent needs. It stops short of describing response shape or pagination, but an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short, front-loaded lines: purpose first, then the data-lag caveat, then the API/quota note. Each sentence carries distinct information, though the quota sentence is slightly fragmented across two lines.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter analytics tool with a full output schema and complete annotation coverage, the description supplies the two things the schema cannot: the separate-API prerequisite and the freshness caveat. Nothing an agent needs before calling is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the parameter docs are unusually rich (dimension-specific metric constraints, limit caps, relative date formats), so the schema carries the load. The description adds nothing about parameters beyond mentioning 'one dimension' as the breakdown model.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource plus its two output shapes (totals vs. one-dimension breakdown), which is more precise than a generic 'get analytics'. It implicitly separates itself from Data API siblings by naming the separate YouTube Analytics API, but never names an actual sibling like get_impressions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Conveys the prerequisite (Analytics API must be enabled, quota is separate from Data API units) and warns about incomplete recent data, but gives no explicit guidance on when to choose this over get_impressions or list_activities. Usage is implied rather than routed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.