Sign in
Analytics

Get YouTube video retention curve

Returns the audience retention curve for a single YouTube video, plus the video's duration for rendering the curve on a time axis. The curve has up to 100 points (elapsedVideoTimeRatio 0.01-1.0) aggregated over the whole date range; YouTube does not support per-day retention breakdowns.

audienceWatchRatio is the absolute share of viewers watching at that point in the video and can exceed 1 (rewinds and looping, common on Shorts). relativeRetentionPerformance compares against videos of similar length (0 = worst, 0.5 = median, 1 = best). YouTube returns an empty curve for videos with very few views or before analytics processing completes (2-3 day delay).

Requires yt-analytics.readonly scope (re-authorization may be needed).

get/v1/analytics/youtube/video-retention

Query parameters

videoIdstring required

The YouTube video ID (e.g., "dQw4w9WgXcQ")

accountIdstring required

The Zernio account ID for the YouTube account

fromDatestring date

Start date (YYYY-MM-DD). Defaults to the video's publish date (lifetime curve).

toDatestring date

End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day (YouTube finalizes analytics with a ~3-day delay). An explicit toDate is honored up to today: days inside the delay window are provisional and may still be revised by YouTube (see provisionalSince in the response).

startDatestring date

Alias of fromDate, kept for existing callers

endDatestring date

Alias of toDate, kept for existing callers

Response

Audience retention curve

successboolean
accountIdstring

The Zernio account ID for the YouTube account

videoIdstring

The YouTube video ID

titlestring nullable

Video title

publishedAtstring date-time nullable

When the video was published on YouTube

durationSecondsinteger nullable

Video length in seconds (from YouTube contentDetails.duration)

provisionalSincestring date

Present only when the range reaches into YouTube's ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.

notestring

Present only when the curve is empty, explaining why

Example response

{
  "success": true
}

Changes