Skip to main content
GET
Get YouTube video retention curve

Request contract

  • Method and path: GET /apis/v1/social/analytics/youtube/video-retention
  • Availability: enabled
  • Request URL template: https://api.aisa.one/apis/v1/social/analytics/youtube/video-retention
  • videoId: query; required
  • accountId: query; required
  • fromDate: query; optional
  • toDate: query; optional
  • startDate: query; optional
  • endDate: query; optional
  • Runtime facts: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd
Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

Cost and request rules

A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

videoId
string
required

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

accountId
string
required

One of your social accounts (acc_...).

Pattern: ^acc_[0-9A-Za-z]{22}$
fromDate
string<date>

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

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

startDate
string<date>

Alias of fromDate, kept for existing callers

endDate
string<date>

Alias of toDate, kept for existing callers

Response

Audience retention curve

accountId
string

One of your social accounts (acc_...).

Pattern: ^acc_[0-9A-Za-z]{22}$
dateRange
object
durationSeconds
integer | null

Video length in seconds (from YouTube contentDetails.duration)

note
string

Present only when the curve is empty, explaining why

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.

publishedAt
string<date-time> | null

When the video was published on YouTube

retentionCurve
object[]

Up to 100 points covering the video timeline, aggregated over the date range. Can be empty when YouTube has no retention data for the video in the given range.

scopeStatus
object
success
boolean
title
string | null

Video title

videoId
string

The YouTube video ID