---
title: "Get a YouTube video transcript"
method: GET
path: "/v1/accounts/{accountId}/youtube-captions"
tags: ["Connect"]
---

# Get a YouTube video transcript

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

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). Pass `refresh=true` only when the captions actually changed on YouTube, since that re-downloads.

Notes:
- Only videos owned by this connected channel. Anything else returns 404.
- `contentDetails.caption` in YouTube's own API reads `false` on videos that DO have a serving auto-generated track, so it is not a usable availability signal. Call this endpoint and handle the 404.
- YouTube generates auto-captions only for videos with recognisable speech, and can take a few hours after upload to publish them.

## Path parameters

- `accountId` string, required

## Query parameters

- `videoId` string, required
- `language` string
- `format` 'json' | 'srt'
- `refresh` boolean

## Response `200`

The transcript.

- object
  - `accountId` string
  - `videoId` string
  - `language` string — The language of the returned track.
  - `trackId` string — YouTube's own caption track id.
  - `trackKind` 'asr' | 'standard' — `asr` is YouTube's auto-generated track; `standard` was uploaded by the channel.
  - `source` 'cache' | 'youtube' — `cache` when served from our stored copy, `youtube` when this call spent the quota units.
  - `fetchedAt` string, date-time — When the stored copy was downloaded from YouTube.
  - `text` string — The whole transcript as one paragraph, no timings.
  - `cues` object[] — Timed cues. Present when format is json. Auto-generated cues overlap in time by design (captions roll), so `start` can precede the previous cue's `end`.
    - `start` number — Seconds from the start of the video.
    - `end` number
    - `text` string
  - `srt` string — Raw SubRip body. Present when format is srt.
  - `availableTracks` object[] — Every track on the video, so you can re-request another language. On a cached read this is the listing as it stood when we downloaded, so a language added to the video since then appears only after a `refresh=true` or when you request that language directly.
    - `trackId` string
    - `language` string
    - `trackKind` 'asr' | 'standard'
    - `name` string — The track's display name. Empty for auto-generated tracks.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `404` — Account not found, the video does not belong to this channel (`video_not_found`), or the video has no caption track in the requested language (`captions_not_found`).

## Changes

- **2026-09-16** `3e6ddf2a99ea` — 2 info
  - added the optional property `details/budgetScope` to the response with the `400` status
  - added the optional property `details/budgetScope` to the response with the `404` status
- **2026-09-15** `0dba7d004d75` — 4 info
  - added the optional property `details/quotaExhausted` to the response with the `400` status
  - added the optional property `details/quotaExhausted` to the response with the `404` status
  - added the optional property `details/quotaScope` to the response with the `400` status
  - added the optional property `details/quotaScope` to the response with the `404` status
- **2026-08-28** `df4e1192cfc4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/accounts/:accountId/youtube-captions/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/dd3865482f9f?raw)