Top videos by a metric
yt_top_videosRead-onlyIdempotent
Rank a channel's videos by views, watch time, or other metrics over a date range to find top performers. Returns video IDs and optionally titles for retention, traffic, and episode analysis.
Instructions
Rank the channel's videos over a date range by views, watch time, average view duration, or subscribers gained. Use this to find which videos to look at more closely — the IDs it returns feed yt_audience_retention, yt_traffic_sources, and yt_episode_race. max_results is capped at 200 by the API. Setting resolve_titles=true spends 1 YouTube Data API quota unit per 50 videos (default daily budget: 10,000 units); the Analytics query itself does not draw on that budget. Pass resolve_titles=false to return bare video IDs and spend none.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| metrics | No | Metrics to return per video. | |
| sort_by | No | Metric to rank by, highest first. | views |
| end_date | Yes | End date, YYYY-MM-DD, inclusive. YouTube Analytics lags roughly 2-3 days, so ending the range at today usually returns zeros for the last few days. | |
| start_date | Yes | Start date, YYYY-MM-DD, inclusive. Interpreted in the channel's timezone. | |
| max_results | No | How many videos to return, 1-200. Keep it low; rows cost tokens. | |
| resolve_titles | No | Look up each video's title so the result is readable. Setting resolve_titles=true spends 1 YouTube Data API quota unit per 50 videos (default daily budget: 10,000 units); the Analytics query itself does not draw on that budget. Pass resolve_titles=false to return bare video IDs and spend none. |