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

{
  "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

{
  "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)

{
  "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)

{
  "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.