canonical: https://jentic.com/apis/googleapis.com/youtube-analytics

# Google YouTube Analytics API

The YouTube Analytics API exposes channel and content performance data for the authorised YouTube account. It supports targeted reports - views, watch time, subscribers gained, demographics, traffic sources - driven by metric, dimension, and filter parameters, plus group and groupItem management to roll multiple videos or channels into named cohorts. This is the API for live, ad-hoc analytics queries; bulk historical exports use the separate YouTube Reporting API.

## For AI agents

Query YouTube channel and video analytics by metric, dimension, and filter. Manage analytics groups and items for cohort-based reporting. Read-only over OAuth.

## Scope

Does not handle video uploads, comment moderation, monetisation configuration, or non-YouTube analytics - use for querying YouTube channel and video performance data only.

## Capabilities

- Run targeted reports combining metrics like views and estimatedMinutesWatched with dimensions such as day, country, or video
- Filter reports by channel, video, group, or geographic region
- Create analytics groups to bundle videos or channels for cohort analysis
- Add and remove groupItems to maintain cohort membership over time
- List existing groups and groupItems for the authorised account

## Use cases

### Creator dashboard with daily KPIs

Power a creator's internal dashboard with daily views, estimated watch time, and subscribers-gained pulled directly from YouTube Analytics. The reports endpoint accepts metric, dimension, and filter parameters so the dashboard can render channel-level overviews and per-video drill-downs from a single API surface. Refresh frequency is bounded by YouTube's analytics processing latency, typically 24-48 hours.

Example prompt: Call GET /v2/reports with ids=channel==MINE, metrics=views,estimatedMinutesWatched, dimensions=day, startDate and endDate covering the last 28 days, and return the rows.

### Cohort analytics with groups

Studios and multi-channel networks group related videos - by show, season, or sponsorship - using the groups and groupItems endpoints, then run reports filtered by group ID. This produces clean cohort metrics without retrofitting tags on every video. The grouping API is the right primitive for any analytics workflow that needs stable cohort definitions over time.

Example prompt: POST /v2/groups to create a group named Q4 Sponsored, add three videos via POST /v2/groupItems, then GET /v2/reports filtered by group=={group_id}.

### Audience demographic deep-dive

Marketing teams query demographic dimensions - ageGroup, gender, country - to understand who is watching specific videos before greenlighting follow-up content. The reports endpoint exposes these dimensions alongside engagement metrics in one query. This replaces the manual exports many teams used to copy out of YouTube Studio.

Example prompt: Call GET /v2/reports with metrics=viewerPercentage, dimensions=ageGroup,gender, and a filter on a specific video to get demographic breakdown.

### Agent-driven channel reporting through Jentic

An analytics agent can compose multi-step reports - daily views, top videos, audience country mix - through Jentic without engineers writing OAuth and pagination glue. The agent searches Jentic for query youtube channel analytics, loads the reports operation, and executes it with the metrics and dimensions it needs. Tokens stay isolated inside your Jentic One instance.

Example prompt: Through Jentic, run three GET /v2/reports calls covering daily views, top videos by watch time, and country breakdown, then summarise the result in plain English.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v2/reports | Run an analytics report |
| GET | /v2/groups | List analytics groups |
| POST | /v2/groups | Create an analytics group |
| GET | /v2/groupItems | List items in a group |
| POST | /v2/groupItems | Add an item to a group |
| DELETE | /v2/groupItems | Remove an item from a group |

## Key resources

- **reports** — Targeted analytics queries by metric, dimension, and filter
- **groups** — Named cohorts of videos or channels for grouped reporting
- **groupItems** — Membership of items within a group

## Why Jentic

- **Setup:** Wiring the YouTube Analytics API by hand means setting up OAuth 2.0 with the channel owner's refresh token, refreshing access tokens, and matching report queries against the youtubeanalytics.googleapis.com host. Through Jentic you install once, import the YouTube Analytics API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** The YouTube Analytics API carries its metrics and dimensions in the request query and body, so you limit the agent to the operations it needs, such as querying reports or listing groups. You choose the operations it may call, so deleting group items is not included unless you add it.
- **Credential handling:** Your YouTube Analytics OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. Its refresh token never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get channel views over time' or 'list audience demographics', and Jentic returns the reports operation with its metric and dimension parameters so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **YouTube Reporting API** — Bulk CSV exports of historical analytics for warehousing
- **YouTube Data API** — Channel and video metadata, search, and content management
- **Cloud Monitoring API** — General-purpose metrics and dashboards for non-YouTube data

## FAQ

### What authentication does the YouTube Analytics API use?

OAuth 2.0 (Oauth2 and Oauth2c schemes) with the youtube.readonly or yt-analytics.readonly scopes for read access. Reports are scoped to the authorised channel. Through Jentic the OAuth credentials are stored encrypted and short-lived access tokens are minted at execution time.

### What is the difference between this API and YouTube Reporting?

YouTube Analytics is for ad-hoc, parameterised queries that return JSON in real time (with the standard analytics processing lag). YouTube Reporting is for scheduled bulk CSV exports of historical data and is better for warehousing. Many teams use both: Analytics for dashboards, Reporting for backfill.

### What are the rate limits for the YouTube Analytics API?

Per-project quotas are managed in the Cloud Console under APIs and Services. The published default is in the order of tens of thousands of queries per day per project, which is enough for most dashboards. Heavy fan-out workloads should request a quota increase or batch queries by dimension.

### How do I run a report through Jentic?

Search Jentic for query youtube analytics, load the schema for GET /v2/reports, and execute it with ids, metrics, dimensions, startDate, and endDate. Group filters and sort orders are exposed as additional query parameters.

### Can I group videos or channels for cohort reporting?

Yes. POST /v2/groups creates a group, POST /v2/groupItems adds a video or channel, and DELETE /v2/groupItems removes one. Reports can then be filtered with group=={group_id} to scope metrics to that cohort.

### Can I limit what my agent is allowed to do with the YouTube Analytics API?

Yes. Because you run Jentic One yourself, your own rules decide which YouTube Analytics operations the agent may call, so you can allow read-only work like querying reports (GET /v2/reports) and listing groups (GET /v2/groups) while withholding everything else. Write operations such as creating a group (POST /v2/groups), adding a group item (POST /v2/groupItems), or deleting a group item (DELETE /v2/groupItems) are only available if you explicitly add them. The OAuth credential is held by your own instance and injected at execution time, so the agent acts only within the scopes and operations you grant.