query_channel_analytics
Retrieve YouTube Analytics data for your channel, including views, watch time, and traffic sources. Supports date ranges and optional grouping by dimensions like day or video.
Instructions
Query YouTube Analytics for the authenticated channel. Returns tabular data — useful for views/watch-time/retention/traffic-source reports. Date-ranged and optionally grouped by dimensions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | YYYY-MM-DD (inclusive) | |
| end_date | Yes | YYYY-MM-DD (inclusive) | |
| metrics | No | Comma-separated metric names (see YouTube Analytics API). Defaults cover the most common creator-dashboard stats. | views,estimatedMinutesWatched,averageViewDuration,subscribersGained |
| dimensions | No | Comma-separated dimensions, e.g. 'day', 'video', 'country'. Omit for channel totals. | |
| filters | No | Filter expression, e.g. 'video==VIDEO_ID' to scope to one video, or 'country==US'. | |
| sort | No | Sort spec, e.g. '-views' for descending by views | |
| max_results | No |
Implementation Reference
- src/youtube/client.ts:298-317 (helper)Helper method on YouTubeClient that builds and sends the YouTube Analytics API request with channel==MINE and the provided parameters.
async analyticsQuery(params: { startDate: string; endDate: string; metrics: string; dimensions?: string; filters?: string; sort?: string; maxResults?: number; }): Promise<AnalyticsResponse> { return this.analyticsGet<AnalyticsResponse>("/reports", { ids: "channel==MINE", "start-date": params.startDate, "end-date": params.endDate, metrics: params.metrics, dimensions: params.dimensions, filters: params.filters, sort: params.sort, maxResults: params.maxResults ? String(params.maxResults) : undefined, }); } - src/youtube/client.ts:91-97 (helper)Low-level helper that constructs the YouTube Analytics API URL with query parameters and performs a GET request via the shared request method.
async analyticsGet<T>(path: string, params: Record<string, string | undefined>): Promise<T> { const url = new URL(`${ANALYTICS_API}${path}`); for (const [k, v] of Object.entries(params)) { if (v !== undefined) url.searchParams.set(k, v); } return this.request<T>(url.toString(), { method: "GET" }); }