YouTube Studio MCP

Overview Schema Source Related Servers Discussions Admin

Metrics over time

get_metrics_over_time

Read-onlyIdempotent

Retrieve YouTube analytics metrics over time by day, week, month, or year to analyze trends, build growth charts, and compare subscriber gains versus losses for a channel or video.

Instructions

A time series of metrics by day, week, month or year — for trend analysis and growth charts. Adds netSubscribers when gained and lost are both requested. Buckets cut off by the date range are flagged partial=true.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_metrics_over_time"
  }
}

Input Schema

Name	Required	Description	Default
`period`	No	Named date range, Studio-style. Rolling ranges end at the latest complete day of data (analytics lag ~2-3 days; dates are US Pacific). Ignored when start_date is set.	last_90_days
`metrics`	No	Analytics metric names. Default: views, estimatedMinutesWatched, subscribersGained, subscribersLost. Others: engagedViews, likes, comments, shares, averageViewDuration, averageViewPercentage, estimatedRevenue, estimatedAdRevenue, cpm, playbackBasedCpm, ...
`save_to`	No	Optional file to also save the rows to (.csv or .json). A bare filename goes in the output directory; absolute paths are allowed.
`end_date`	No	Custom range end, YYYY-MM-DD (inclusive). Defaults to the latest complete day.
`video_id`	No	Limit to one video (11-character ID, e.g. 'dQw4w9WgXcQ'). Omit for the whole channel.
`start_date`	No	Custom range start, YYYY-MM-DD. Overrides `period`.
`granularity`	No	Bucket size. Weeks start on Monday.	day
`content_type`	No	Only Shorts, regular videos, or live streams.
`include_cumulative_subscribers`	No	Add totalSubscribers per bucket (running total of net subscribers since the channel started; great for growth charts). Channel-wide only.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 11, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's added value here is real: it discloses that netSubscribers is derived only when gained and lost are both requested, and that boundary buckets are marked partial=true. Those are non-obvious output behaviors an agent could not predict from annotations alone.

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

Conciseness5/5

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

Three short sentences, front-loaded with what the tool returns and its purpose, then two concrete behavioral caveats. No filler, no restatement of the name or title.

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

Completeness4/5

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

With nine optional parameters, an output schema, and full annotations, the description covers the main interpretive facts needed to call it correctly. It stays silent on defaults for period and granularity and on row limits, but those are documented in the schema, so the remaining gap is minor.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, and the description earns one step above it by explaining a cross-parameter interaction (requesting subscribersGained and subscribersLost together produces netSubscribers) that no single parameter doc states. It does not, however, touch period versus start_date precedence or granularity, which remain schema-only.

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?

Names the resource (a metrics time series) and the bucket dimensions (day/week/month/year) with a stated use case: trend analysis and growth charts. That implicitly separates it from summary/breakdown siblings, but no sibling is named explicitly, so differentiation is left partly to inference.

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?

The phrase 'for trend analysis and growth charts' implies when this tool fits, and nothing suggests when it does not. No alternative (e.g. query_analytics or get_performance_summary) is mentioned, so an agent must infer the boundary elsewhere.

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