API resource

YouTube

Channel analytics, audience demographics and retention, plus playlists and captions for your uploads.

Get YouTube channel insights

GET/v1/analytics/youtube/channel-insights

Works on: YouTube

Returns channel-scoped aggregate metrics from YouTube Analytics API v2. Saves you from looping /v1/analytics/youtube/daily-views over every video when you only need channel totals. Response shape matches /v1/analytics/instagram/account-insights so the same client handling works. Requires yt-analytics.readonly scope (412 with reauthorizeUrl if missing). Data has a 2-3 day delay (endDate is clamped accordingly). Max 89 days, defaults to last 30 days. Requires analytics access on your plan. NOT exposed: impressions (Studio thumbnail impressions) and impressionsClickThroughRate.

Query parameters

accountIdstringrequired

The account id for the YouTube account.

metricsstring

Comma-separated list. Defaults to "views,estimatedMinutesWatched,subscribersGained,subscribersLost".

fromDatestring

Start date (YYYY-MM-DD). Defaults to 30 days ago.

toDatestring

End date (YYYY-MM-DD). Defaults to today. YouTube Analytics has a 2-3 day delay, so the fetch is internally clamped to 3 days ago; any requested range extending beyond that returns zero values for the tail days. The response's dateRange.until field reflects your requested value.

sincestring

Alias of fromDate, kept for existing callers

untilstring

Alias of toDate, kept for existing callers

metricTypestring

"total_value" (default) returns aggregated totals. "time_series" returns per-day values in the "values" array.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/youtube/channel-insights?accountId=acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "accountId": "acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X",
  "platform": "youtube",
  "dateRange": {
    "since": "string",
    "until": "string"
  },
  "metricType": "time_series",
  "breakdown": "string",
  "metrics": {},
  "unavailableMetrics": [
    {
      "metric": "string",
      "reason": "not_enrolled",
      "message": "string"
    }
  ],
  "dataDelay": "Data may be delayed up to 48 hours"
}

Get YouTube daily views

GET/v1/analytics/youtube/daily-views

Works on: YouTube

Returns daily view counts for a YouTube video including views, watch time, and subscriber changes. Requires yt-analytics.readonly scope (re-authorization may be needed). YouTube finalizes analytics with a ~3-day delay; by default only finalized days are returned, and an explicit endDate can reach into the delay window (see the endDate parameter). Max 90 days, defaults to last 30 days.

Query parameters

videoIdstringrequired

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

accountIdstringrequired

The Creator OS account ID for the YouTube account

fromDatestring

Start date (YYYY-MM-DD). Defaults to 30 days ago.

toDatestring

End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day (YouTube finalizes analytics with a ~3-day delay).

startDatestring

Alias of fromDate, kept for existing callers

endDatestring

Alias of toDate, kept for existing callers

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/youtube/daily-views?videoId=%3CvideoId%3E&accountId=acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "videoId": "string",
  "durationSeconds": 0,
  "dateRange": {
    "startDate": "2026-09-25T00:00:00.000Z",
    "endDate": "2026-09-25T00:00:00.000Z"
  },
  "provisionalSince": "string",
  "totalViews": 0,
  "dailyViews": [
    {
      "date": "2026-09-25T00:00:00.000Z",
      "views": 0,
      "estimatedMinutesWatched": 0,
      "averageViewDuration": 0,
      "averageViewPercentage": 0,
      "subscribersGained": 0,
      "subscribersLost": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0
    }
  ],
  "lastSyncedAt": "2026-09-25T00:00:00.000Z",
  "scopeStatus": {
    "hasAnalyticsScope": true
  }
}

Get YouTube demographics

GET/v1/analytics/youtube/demographics

Works on: YouTube

Returns audience demographic insights for a YouTube channel, broken down by age, gender, and/or country. Pass videoId to get the audience profile of a single video instead of the whole channel. Age and gender values are viewer percentages (0-100). Country values are view counts. Data is based on signed-in viewers only, with a 2-3 day delay. YouTube suppresses demographics for videos with too few signed-in views, so low-traffic videos can return empty breakdowns. Requires analytics access on your plan.

Query parameters

accountIdstringrequired

The account id for the YouTube account

videoIdstring

YouTube video ID. When provided, demographics are scoped to this single video (must belong to the connected channel; otherwise 404 video_not_found).

breakdownstring

Comma-separated list of demographic dimensions: age, gender, country. Defaults to all three if omitted.

fromDatestring

Start date in YYYY-MM-DD format. Defaults to 90 days ago, or to the video's publish date (lifetime) when videoId is provided.

toDatestring

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

Alias of fromDate, kept for existing callers

endDatestring

Alias of toDate, kept for existing callers

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/youtube/demographics?accountId=acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "accountId": "acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X",
  "platform": "youtube",
  "videoId": "string",
  "title": "string",
  "publishedAt": "2026-09-25T00:00:00.000Z",
  "demographics": {},
  "dateRange": {
    "startDate": "2026-01-01",
    "endDate": "2026-03-31"
  },
  "provisionalSince": "string",
  "note": "Age/gender values are viewer percentages (0-100). Country values are view counts. Data based on signed-in viewers only, with 2-3 day delay."
}

Get YouTube video retention curve

GET/v1/analytics/youtube/video-retention

Works on: YouTube

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

Query parameters

videoIdstringrequired

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

accountIdstringrequired

The Creator OS account ID for the YouTube account

fromDatestring

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

toDatestring

startDatestring

Alias of fromDate, kept for existing callers

endDatestring

Alias of toDate, kept for existing callers

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/youtube/video-retention?videoId=%3CvideoId%3E&accountId=acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "accountId": "acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X",
  "videoId": "string",
  "title": "string",
  "publishedAt": "2026-09-25T00:00:00.000Z",
  "durationSeconds": 0,
  "dateRange": {
    "startDate": "2026-09-25T00:00:00.000Z",
    "endDate": "2026-09-25T00:00:00.000Z"
  },
  "provisionalSince": "string",
  "retentionCurve": [
    {
      "elapsedVideoTimeRatio": 0,
      "audienceWatchRatio": 0,
      "relativeRetentionPerformance": 0,
      "startedWatching": 0,
      "stoppedWatching": 0,
      "totalSegmentImpressions": 0
    }
  ],
  "note": "string",
  "scopeStatus": {
    "hasAnalyticsScope": true
  }
}

List YouTube playlists

GET/v1/accounts/{accountId}/youtube-playlists

Works on: YouTube

Returns the playlists available for a connected YouTube account. Use this to get a playlist ID when creating a YouTube post with the playlistId field.

Path parameters

accountIdstringrequired

No description

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X/youtube-playlists" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "playlists": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "privacy": "public",
      "itemCount": 0,
      "thumbnailUrl": "string"
    }
  ],
  "defaultPlaylistId": "string"
}

Create YouTube playlist

POST/v1/accounts/{accountId}/youtube-playlists

Works on: YouTube

Creates an empty playlist on the connected YouTube channel. Requires a title; privacy defaults to private. Returns the same playlist shape as the list endpoint. Pass the returned playlist.id as platformSpecificData.playlistId when publishing a video. Does not change the account's default playlist. Requires the youtube or youtube.force-ssl OAuth scope. Costs 50 YouTube quota units. This operation is not idempotent and is not automatically retried: repeating a request can create another playlist, including after a timeout. List playlists before retrying an ambiguous failure.

Path parameters

accountIdstringrequired

No description

Body

titlestringrequired

Playlist title. Leading and trailing whitespace is removed.

descriptionstring

Optional playlist description.

privacystring

No description - one of: private, public, unlisted

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X/youtube-playlists" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "<title>"
  }'

Response 200

{
  "playlist": {
    "id": "string",
    "title": "string",
    "description": "string",
    "privacy": "private",
    "itemCount": 0,
    "thumbnailUrl": "string"
  }
}

Set default YouTube playlist

PUT/v1/accounts/{accountId}/youtube-playlists

Works on: YouTube

Sets the default playlist used when publishing videos for this account. When a post does not specify a playlistId, the default playlist is not automatically used (it is stored for client-side convenience).

Path parameters

accountIdstringrequired

No description

Body

defaultPlaylistIdstringrequired

No description

defaultPlaylistNamestring

No description

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X/youtube-playlists" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultPlaylistId": "<defaultPlaylistId>"
  }'

Response 200

{
  "success": true
}

Get a YouTube video transcript

GET/v1/accounts/{accountId}/youtube-captions

Works on: YouTube

Returns the caption track YouTube already holds for one of the connected channel's own videos, as plain text plus timed cues. Use it instead of downloading and transcribing the video yourself. Auto-generated (ASR) tracks are included: YouTube serves them to the channel owner, which is what the connected account is. Uploaded tracks win over auto-generated ones when both exist for a language. Caching: we store the transcript on first read and serve it from there afterwards, so you do not need to cache it yourself. A cached read costs no YouTube quota and does not call YouTube at all. `source` tells you which happened (`youtube` on the first read, `cache` after).

Path parameters

accountIdstringrequired

The connected YouTube account.

Query parameters

videoIdstringrequired

The YouTube video id (the `platformPostId` on a synced external post).

languagestring

BCP-47 language tag as YouTube labels the track. `en` also matches an `en-GB` track. Omit to take the best available track.

formatstring

`json` returns timed `cues`; `srt` returns the raw SubRip body instead. `text` is present either way.

refreshstring

Re-download from YouTube instead of serving the stored copy. Spends 200 quota units.

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X/youtube-captions?videoId=%3CvideoId%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "accountId": "acc_Yt7Kp2Lm9Qx4Vw1Nz8Rc3Hb6Js5Df0Ga2Ue9Ki4Oq7X",
  "videoId": "string",
  "language": "string",
  "trackId": "string",
  "trackKind": "asr",
  "source": "cache",
  "fetchedAt": "2026-09-25T00:00:00.000Z",
  "text": "string",
  "cues": [
    {
      "start": 0,
      "end": 0,
      "text": "string"
    }
  ],
  "srt": "string",
  "availableTracks": [
    {
      "trackId": "string",
      "language": "string",
      "trackKind": "asr",
      "name": "string"
    }
  ]
}

PreviousTikTok NextLinkedIn