YouTube Transcript Actor Fetch YouTube metadata + transcripts in two modes: - Single video - require a YouTube watch URL + a specific language (ISO 639-1). - Channel mode - give a channel handle/URL or UC ID, optional preferred lang, optional date range, and max videos. The actor tries your preferred language, then falls back to the video's default audio language, then (only if no lang provided or still missing) best available captions. Captions are fetched without proxy first, then retried with Residential proxy if needed. --- ## Inputs > Provide either url (single-video mode) or channel fields (channel mode). ### Single video - url (string, required) - Must be a watch URL or 11-char video ID. - lang (string, required) - Transcript language, ISO 639-1 (two letters, e.g., en, nb, fr). Example json { "url": "https://www.youtube.com/watch?v=h3NwAkaBuFg", "lang": "en" } ### Channel mode Provide one of: - channel (string, recommended) - Channel handle or URL. Examples: - @taostats - https://www.youtube.com/@taostats - https://www.youtube.com/channel/UC_x5XG1OV2P6uZZ5FSM9Ttw - channel_id (string, optional) - Exact UC… ID (24 chars total). Optional filters: - lang (string, optional) - Preferred transcript language (ISO 639-1). If not found for a video, we fall back to that video's default audio language; if still none (and you didn't force a lang), we pick best available. - max_videos (integer, default 50, 1-5000) - How many uploads to fetch. - start_date (string, optional) - Start boundary, YYYY-MM-DD (UTC) or ISO 8601 (2024-01-01T00:00:00Z). - end_date (string, optional) - End boundary, YYYY-MM-DD (inclusive) or ISO 8601 (date-only is inclusive via +1 day). Example json { "channel": "https://www.youtube.com/@taostats", "lang": "en", "max_videos": 10, "start_date": "2024-01-01", "end_date": "2024-12-31" } --- ## Language selection rules - Single video: strict. We only include a transcript if the track matches your requested lang. Otherwise transcript: []. - Channel mode: per video 1. Try your preferred lang (if provided). 2. If not found, try that video's default audio language. 3. If still unavailable and you didn't provide lang, pick the best available track. - The row's language field is the actual track language used (ISO 639-1). --- ## Output Per item fields: | Field | Type | Description | |--------------------------|--------------------|-----------------------------------------------------------------------------| | mode | string | "single" or "channel" | | ok | boolean | Operation success flag | | error | object? | Present only when ok=false (code, message) | | video_id | string | YouTube video ID | | title | string | Video title | | description | string? | Video description (omitted if unavailable) | | channel_id | string | Channel ID | | channel_name | string | Channel name | | upload_date | string (RFC3339) | e.g., 2025-08-10T10:00:09+00:00 | | url | string (URI) | Canonical watch URL | | duration_seconds | integer | Duration in seconds | | view_count | integer | YouTube view count | | subscriber_count | integer | Channel subscriber count (omitted if hidden/unavailable) | | like_count | integer | Like count (omitted if unavailable) | | thumbnail | string (URI) | Representative thumbnail URL | | language | string? | Actual transcript language used (ISO 639-1); omitted if unknown | | transcript_lang_source | string? | "user" | "default" | "auto" | | transcript_found | boolean | True if any transcript present | | reason | string? | Why transcript missing (if transcript_found=false) | | kv_ref | object? | KV pointer for offloaded rows: { store, kv_key, content_type } | | transcript_counts | object? | Offloaded rows: { auto, manual } | | transcript_preview | array? | Offloaded rows: preview segments { start:number, dur:number, text:string }| | sha256 | string? | Checksum of the full offloaded JSON | | transcript | array | Segments: { "start":"sec.ms", "end":"sec.ms", "text":"..." } | | transcript_manual | array | Same shape as transcript; manual captions when available | ### Single-video example (inline) json { "mode": "single", "ok": true, "video_id": "h3NwAkaBuFg", "title": "Sample Title", "description": "This is the video description...", "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx", "channel_name": "Sample Channel", "upload_date": "2025-08-10T10:00:09+00:00", "url": "https://www.youtube.com/watch?v=h3NwAkaBuFg", "duration_seconds": 213, "view_count": 154203, "subscriber_count": 482000, "like_count": 8600, "thumbnail": "https://i.ytimg.com/vi/h3NwAkaBuFg/hqdefault.jpg", "language": "en", "transcript_found": true, "transcript": [ { "start": "0.000", "end": "2.000", "text": "Intro line one" }, { "start": "2.001", "end": "4.500", "text": "Intro line two" } ], "transcript_manual": [] } ### Channel example (offloaded) json { "mode": "channel", "ok": true, "video_id": "yRRvHm4so68", "title": "Some Title", "description": "Channel upload description here...", "channel_id": "UCjVXOgEZavu2h4Qt8mK1ZiQ", "channel_name": "Example Channel", "upload_date": "2025-08-10T10:00:09+00:00", "url": "https://www.youtube.com/watch?v=yRRvHm4so68", "duration_seconds": 3537, "view_count": 10221, "subscriber_count": 19500, "like_count": 740, "thumbnail": "https://i.ytimg.com/vi/yRRvHm4so68/hqdefault.jpg", "language": "zh", "transcript_lang_source": "default", "transcript_found": true, "transcript_counts": { "auto": 1250, "manual": 0 }, "transcript_preview": [ { "start": 0.0, "dur": 2.7, "text": "Opening…" }, { "start": 2.7, "dur": 3.0, "text": "Agenda…" }, { "start": 5.7, "dur": 4.2, "text": "…" } ], "sha256": "c0ffee...deadbeef", "kv_ref": { "store": "default", "kv_key": "records__yRRvHm4so68.json", "content_type": "application/json" } } --- ## Billing note (Apify PPR) Apify's pay-per-result counts each dataset item you push. In channel mode, max_videos: 10 means up to 10 billable results (one per video), even if a video has an empty transcript. --- ## Troubleshooting - Invalid input: Single mode requires url and lang. Channel mode requires channel or channel_id. - No captions: Some videos don't provide captions in any language. You'll get transcript: [] and transcript_manual: []. - Language mismatch (single mode): If there's no caption track in your requested lang, we don't substitute another language; transcript will be empty. - Region restrictions: We retry via Residential proxies when the no-proxy attempt fails; success still depends on availability per region/video.