Get captions
Returns YouTube caption-track metadata (best-effort; a valid API key can list public-video tracks) alongside the transcript text served by the unified caption service (same permission/quota/proxy path as POST /v1/transcript). A failed or empty Google track query is reported through trackMetadataStatus/trackMetadataError and never by itself means the video has no captions (captionAvailable may be null). This endpoint never creates an ASR job: requiresAsync: true is returned when the coordinator confirms speech recognition is required — an asr-only request, a confirmed absence of caption tracks, or a confirmed miss of every requested caption language (with captionAvailable staying null) — but never from an upstream fault or the wait budget. It requires the transcripts scope.
Session token (cookie-based auth in browser) or developer API key (tr_ prefix). API keys require the transcripts scope for /v1/transcript and the batches scope for /v1/batch.
In: header
Query Parameters
Optional caption-language priority list; omitted uses the platform default (en). Each entry is tried in order; ASR is not run by this endpoint.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/youtube/captions?videoId=string"{ "videoId": "string", "captionAvailable": true, "tracks": [ {} ], "trackMetadataStatus": "complete", "trackMetadataError": "string", "trackMetadataErrorCode": "string", "language": "string", "transcript": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "platform": "youtube", "externalId": "string", "sourceUrl": "http://example.com", "lang": "string", "title": "string", "channel": "string", "creatorName": "string", "creatorHandle": "string", "creatorUrl": "string", "thumbnailUrl": "string", "durationSec": 0, "publishedAt": "2019-08-24T14:15:22Z", "metadata": {}, "source": "youtube_transcript_api", "status": "pending", "segments": [ { "text": "string", "start": 0, "duration": 0 } ], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }, "cached": true, "status": "success", "requiresAsync": true, "error": { "code": "string", "message": "string" }}