Skip to content

YouTube Analytics API

The YouTube Analytics API brings YouTube video performance data into a product, reporting workflow, automation, or AI system.

Channel Videos Request
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"
Illustrative request
Example line 1

curl -X GET "{{API_BASE_URL}}/v1/analytics?source=platform&platform=youtube&accountId=acc_yt_789&limit=10&p…

Illustrative request
Example line 2

-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.

Request Parameters
FieldLocationMeaningExample / notes
sourceQuery parameterRetrieval mode; platform pulls existing videos from the connected platformsource=platform
platformQuery parameterPlatform filterplatform=youtube
accountIdQuery parameterConnected account identifieraccountId=acc_yt_789
limitQuery parameterPage sizelimit=10
pageQuery parameterPage numberpage=1
x-access-keyHeaderAccess key for the requestx-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.

Response Metrics
FieldType in exampleMeaningNull handling
successbooleanRequest outcometrue in example
totalnumberTotal matching posts1 in example
page / limitnumberPagination echo1 / 10 in example
posts[].sourcestringOrigin of the postplatform in example
posts[].postIdstring or nullAPI post identifiernull for platform-sourced videos
posts[].publishedAtstringPublication timestamp2026-08-28T14:30:00Z in example
posts[].platforms[].platformPostIdstringYouTube video identifierVIDEO_ID in example
posts[].platforms[].platformPostUrlstringYouTube video URLhttps://www.youtube.com/watch?v=VIDEO_ID in example
metrics.viewsnumber or nullVideo views12450 in example
metrics.likesnumber or nullVideo likes342 in example
metrics.commentsnumber or nullVideo comments56 in example
metrics.sharesnumber or nullVideo sharesnull in example
metrics.impressions / reach / saves / clicksnumber or nullAdditional metrics when availablenull in example
metrics.engagementRatenumber or nullCalculated engagement ratenull in example; do not treat as zero
watchTimeMinutesfield name from FAQTotal watch time in minutesNot shown in captured JSON example
averageViewDurationfield name from FAQAverage view duration in secondsNot 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.

Failure and Edge Cases
CaseWhat to expectCheck before using the data
Null metricMetric is null while others are populatedExclude that metric for that video; do not substitute zero
Existing platform videosource is platform and postId is nullUse platformPostId and platformPostUrl as the video identity
YouTube Shorts vs long-formSame endpoint and response formatUse one parser; do not assume a separate Shorts endpoint
Date range filteringResults narrowed to a reporting periodConfirm parameter names in the reference; not shown in the captured example
Paginationtotal, page, and limit describe the result setFetch 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.

Channel Videos Response
{
    "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
            }
          }
        ]
      }
    ]
}