---
title: "Get YouTube video retention curve"
method: GET
path: "/v1/analytics/youtube/video-retention"
tags: ["Analytics"]
---

# Get YouTube video retention curve

`GET /v1/analytics/youtube/video-retention`

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

## Query parameters

- `videoId` string, required
- `accountId` string, required
- `startDate` string, date
- `endDate` string, date

## Response `200`

Audience retention curve

- YouTubeVideoRetentionResponse
  - `success` boolean
  - `accountId` string — The Zernio account ID for the YouTube account
  - `videoId` string — The YouTube video ID
  - `title` string, nullable — Video title
  - `publishedAt` string, date-time, nullable — When the video was published on YouTube
  - `durationSeconds` integer, nullable — Video length in seconds (from YouTube contentDetails.duration)
  - `dateRange` object
    - `startDate` string, date
    - `endDate` string, date
  - `provisionalSince` string, 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.
  - `retentionCurve` object[] — Up to 100 points covering the video timeline, aggregated over the date range. Empty for videos with very few views.
    - `elapsedVideoTimeRatio` number — Position in the video as a ratio (0.01-1.0, exclusive end of each interval)
    - `audienceWatchRatio` number — Absolute share of viewers watching at this point. Can exceed 1 (rewinds/looping, common on Shorts).
    - `relativeRetentionPerformance` number — Retention vs videos of similar length (0 = worst, 0.5 = median, 1 = best)
    - `startedWatching` integer — Viewers who started watching in this segment
    - `stoppedWatching` integer — Viewers who stopped watching in this segment
    - `totalSegmentImpressions` integer — Total views of this segment, including rewatches
  - `note` string — Present only when the curve is empty, explaining why
  - `scopeStatus` object
    - `hasAnalyticsScope` boolean

## Other responses

- `400` — Bad request (missing or invalid parameters)
- `401` — Unauthorized
- `402` — Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.
- `403` — Access denied to this account
- `404` — Video not found, or it does not belong to this YouTube channel
- `412` — Missing YouTube Analytics scope
- `500` — Internal server error

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/0942091eaa8c/schema)