YouTube Analytics API
The YouTube Analytics API brings YouTube video performance data into a product, reporting workflow, automation, or AI system.
curl -X GET "{{API_BASE_URL}}/v1/analytics?source=platform&platform=youtube&accountId=acc_yt_789&limit=10&page=1" \
-H "x-access-key: your-api-key"curl -X GET "{{API_BASE_URL}}/v1/analytics?source=platform&platform=youtube&accountId=acc_yt_789&limit=10&p…
-H "x-access-key: your-api-key"
It retrieves supported performance data for YouTube videos from connected YouTube channels, including views, likes, comments, and shares, so a team can analyze videos without building a separate reporting pipeline for each channel.
YouTube Analytics API: retrieve video performance for connected channels
This endpoint returns performance figures at video level for channels you have connected. A request for channel videos yields a paginated collection of posts. Each item carries two views of the numbers: an aggregated metrics object, and a YouTube-specific entry nested under platforms. That YouTube entry names the video through platformPostId and platformPostUrl and holds the metrics belonging to that video. Reach for the aggregated object when a post covers several platforms; reach for the platform object when only the YouTube figures matter.
When the goal is to cover uploads that already exist on the channel, rather than only items published via the API, set source=platform so recent channel content is fetched directly from the platform. For one video in isolation, include its video identifier alongside platform=youtube and the connected account identifier. Apply date-range filtering when a particular reporting or campaign window is required, and control result size and paging through limit and page. Performance-based sorting is described as available for surfacing top performers within a period, yet the captured request example shows no sorting parameter name, so that name should not be assumed until the reference confirms it.
Validate the payload before it reaches a dashboard. Unavailable metrics come back as null — the example shows this for impressions, reach, shares, saves, clicks and engagementRate. Interpret null as absent for that video, not as zero, and retain the video in the list so video counts and totals stay coherent. Also confirm success is true, page and limit echo what was requested, and total aligns with the posts returned before summing views, likes, comments and shares across the page.
Contract snapshot: GET {{API_BASE_URL}}/v1/analytics, required header, query parameters, and 202 response shape
Calls go to GET {{API_BASE_URL}}/v1/analytics, with the access key supplied in the x-access-key header. In the channel videos example, source=platform, platform=youtube, accountId, limit and page appear as query parameters. The example response is labelled 202 and includes success, total, page, limit and a posts array. Every post includes source, postId, publishedAt, aggregated metrics and a platforms array. Items sourced from the platform show postId as null and source as platform, separating them from posts created through the API.
Field map: views, likes, comments, shares, watchTimeMinutes, averageViewDuration, engagementRate, platformPostId, platformPostUrl
At video level, the metrics cover views, likes, comments and shares for each supported YouTube video, allowing performance to be followed from publication onward. Watch time is split into two measures: total watch time in minutes through watchTimeMinutes, and average view duration in seconds through averageViewDuration. Keeping those units distinct matters during comparison — accumulated viewing is shown by the first, while typical per-view length is shown by the second.
Engagement rate is derived automatically from supported interactions — likes, comments and shares — relative to video views. The example returns engagementRate as null even though views, likes and comments are present, so a null engagement rate should be treated as unavailable rather than recalculated client-side. YouTube Shorts use the same endpoint and response format as long-form videos, meaning one parsing path can serve both, with format distinguished only if another field in your data identifies it.
Worked example: channel videos with source=platform, platform=youtube, accountId, limit, page
Begin with the channel videos request in the Channel Videos Request example, using source=platform, platform=youtube, accountId, limit and page. Inside platforms, read the YouTube entry for platformPostId, platformPostUrl and metrics; reserve the aggregated object for cross-platform totals. Then compare the reply with the Channel Videos Response example, checking success, total, page, limit, publishedAt and which metrics are nullable.
For a single video, retain platform=youtube and the connected account identifier and add the YouTube video ID as described in the FAQ. For a date range, apply the endpoint's date-range filtering and page through the results. After each call, look for null metrics, reconcile the video count with total, and only then sort or aggregate. Where a metric is null, leave it out of that video's sum or average and record the gap instead of inserting zero.
Formats: channel videos, single video, date range filtering, sorting and pagination
Three formats are described against the same endpoint. Channel videos enumerates videos from a connected channel with pagination. Single video returns supported analytics for one YouTube video, identified by video ID, platform and account. Date range filtering confines video analytics to a chosen period for reporting or campaign analysis. Only the channel videos parameter set appears in the captured example, so single-video and date-range parameter names should be confirmed in the API reference before implementation.
Shorts and long-form parity, existing videos, and null metric handling
YouTube Shorts and long-form videos are both handled through the same endpoint and response format. Existing videos are included when source=platform is used, so coverage is not restricted to videos published through the API. Null metrics are the principal edge case: a video may return views, likes and comments while impressions, reach, shares, saves, clicks and engagementRate are null. Charts and exports should therefore tolerate nulls metric by metric, and a null engagement rate should never be read as a calculated zero.
Decision criteria: unified endpoint vs YouTube Data API setup, OAuth consent, and quota management
Choose the unified endpoint when video analytics need to live inside a product, reporting workflow, automation or AI system without taking on the YouTube Data API, OAuth consent screens and quota management directly. The connected-account workflow covers the underlying integration for this analytics use case. Direct YouTube Data API management is preferable only when platform capabilities beyond the metrics and formats described here are required, or when the team already runs OAuth and quota handling for other YouTube features. That distinction concerns scope and operational ownership, not metric definitions, which remain views, likes, comments, shares, watch time and engagement rate.
| Field | Location | Meaning | Example / notes |
|---|---|---|---|
| source | Query parameter | Retrieval mode; platform pulls existing videos from the connected platform | source=platform |
| platform | Query parameter | Platform filter | platform=youtube |
| accountId | Query parameter | Connected account identifier | accountId=acc_yt_789 |
| limit | Query parameter | Page size | limit=10 |
| page | Query parameter | Page number | page=1 |
| x-access-key | Header | Access key for the request | x-access-key: your-api-key |
Exact parameter names and values are from the captured channel videos request example; single-video and date-range parameter names were not shown and are not invented here.
| Field | Type in example | Meaning | Null handling |
|---|---|---|---|
| success | boolean | Request outcome | true in example |
| total | number | Total matching posts | 1 in example |
| page / limit | number | Pagination echo | 1 / 10 in example |
| posts[].source | string | Origin of the post | platform in example |
| posts[].postId | string or null | API post identifier | null for platform-sourced videos |
| posts[].publishedAt | string | Publication timestamp | 2026-08-28T14:30:00Z in example |
| posts[].platforms[].platformPostId | string | YouTube video identifier | VIDEO_ID in example |
| posts[].platforms[].platformPostUrl | string | YouTube video URL | https://www.youtube.com/watch?v=VIDEO_ID in example |
| metrics.views | number or null | Video views | 12450 in example |
| metrics.likes | number or null | Video likes | 342 in example |
| metrics.comments | number or null | Video comments | 56 in example |
| metrics.shares | number or null | Video shares | null in example |
| metrics.impressions / reach / saves / clicks | number or null | Additional metrics when available | null in example |
| metrics.engagementRate | number or null | Calculated engagement rate | null in example; do not treat as zero |
| watchTimeMinutes | field name from FAQ | Total watch time in minutes | Not shown in captured JSON example |
| averageViewDuration | field name from FAQ | Average view duration in seconds | Not shown in captured JSON example |
Types are as shown in the captured example response; watchTimeMinutes and averageViewDuration are named in the recovered FAQ but do not appear in the captured JSON example.
| Case | What to expect | Check before using the data |
|---|---|---|
| Null metric | Metric is null while others are populated | Exclude that metric for that video; do not substitute zero |
| Existing platform video | source is platform and postId is null | Use platformPostId and platformPostUrl as the video identity |
| YouTube Shorts vs long-form | Same endpoint and response format | Use one parser; do not assume a separate Shorts endpoint |
| Date range filtering | Results narrowed to a reporting period | Confirm parameter names in the reference; not shown in the captured example |
| Pagination | total, page, and limit describe the result set | Fetch remaining pages before aggregating across a channel |
Derived from the captured example and FAQ; no additional error codes were shown in the source.
Frequently asked questions
Which YouTube metrics can I retrieve?
Expect view counts plus interaction counts for likes, comments and shares, alongside watch-time measures and a derived engagement figure where the service supplies them.
Do analytics work for YouTube Shorts?
Yes — short-form clips and longer uploads share one endpoint and one response shape, so your parser does not need a separate Shorts branch.
Do I need my own YouTube API credentials?
For this workflow, credential upkeep sits with the connected-account setup rather than with a separate YouTube developer project you maintain yourself.
How is YouTube watch time returned?
Accumulated viewing time arrives as watchTimeMinutes, expressed in minutes. Per-view length arrives as averageViewDuration, expressed in seconds.
How is YouTube engagement rate calculated?
The service derives it from the interactions it can measure — likes, comments and shares — set against the video's view count. When inputs are missing it may return null instead of a number.
Can I get analytics for a specific YouTube video?
Yes. Include the video identifier, set platform=youtube, and include the connected account identifier; the response then covers that single video.
Can I retrieve analytics for existing YouTube videos?
Yes. Setting source=platform fetches recent uploads straight from the connected channel, including videos you never published through this API.
Can I filter YouTube analytics by date?
Yes. Date-range filtering is supported, so you can restrict results to the reporting or campaign window you care about.
Can I use YouTube analytics in a creator or video-performance dashboard?
Yes. Metrics, channel lookups, filtering, sorting and pagination give you the building blocks for a creator or video-performance dashboard of your own.
{
"success": true,
"total": 1,
"page": 1,
"limit": 10,
"posts": [
{
"source": "platform",
"postId": null,
"publishedAt": "2026-08-28T14:30:00Z",
"aggregated": {
"impressions": null,
"reach": null,
"likes": 342,
"comments": 56,
"shares": null,
"saves": null,
"clicks": null,
"views": 12450,
"engagementRate": null
},
"platforms": [
{
"platform": "youtube",
"platformPostId": "VIDEO_ID",
"platformPostUrl": "https://www.youtube.com/watch?v=VIDEO_ID",
"metrics": {
"impressions": null,
"reach": null,
"likes": 342,
"comments": 56,
"shares": null,
"saves": null,
"clicks": null,
"views": 12450,
"engagementRate": null
}
}
]
}
]
}