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

You can provide either url (single-video mode) or channel fields (channel mode).

Single video

• url (string, required) — Must be exactly a watch URL: https://www.youtube.com/watch?v=VIDEO_ID (11-char 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 (paging supported).
• start_date (string, optional) — Start boundary, YYYY-MM-DD (UTC) or full ISO 8601 (2024-01-01T00:00:00Z).
• end_date (string, optional) — End boundary, YYYY-MM-DD (inclusive) or full ISO 8601 (date-only is treated inclusive via +1 day internally).

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

The actor writes one dataset item per video. For single-video mode, that’s 1 item. For channel mode, it’s up to max_videos items (one per video).

Per item fields:

Field	Type	Description
mode	string	"single" or "channel"
ok	boolean	Success flag for this row
error	object?	Present only when ok=false (e.g., MetadataUnavailable)
video_id	string	11-char YouTube video ID
title	string	Video title
channel_id	string	Channel ID
channel_name	string	Channel name
upload_date	string (ISO 8601)	Published date/time, e.g. "2024-06-01T12:34:56+00:00"
url	string (URI)	Canonical watch URL
duration_seconds	integer	Video length in seconds
view_count	integer	View count at fetch time (may be 0 if unavailable)
subscriber_count	integer	Channel subscriber count (omitted if hidden/unavailable)
language	string?	Actual transcript language used (ISO 639‑1); omitted if unknown
transcript_lang_source	string?	"user" (matched your lang), "default" (video’s default), or "auto"
transcript	array	Each item: { "start": "sec.ms", "end": "sec.ms", "text": "..." }

Notes

• Fields with no value are omitted (not null), keeping schema strict.
• We always include transcript (empty array if not available).

Single-video example output

{
  "mode": "single",
  "ok": true,
  "video_id": "h3NwAkaBuFg",
  "title": "Sample Title",
  "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
  "channel_name": "Sample Channel",
  "upload_date": "2024-06-01T12:34:56+00:00",
  "url": "https://www.youtube.com/watch?v=h3NwAkaBuFg",
  "duration_seconds": 213,
  "view_count": 154203,
  "subscriber_count": 482000,
  "language": "en",
  "transcript": [
    { "start": "0.000", "end": "2.000", "text": "Intro line one" },
    { "start": "2.001", "end": "4.500", "text": "Intro line two" }
  ]
}

Channel example (per-item shape)

{
  "mode": "channel",
  "ok": true,
  "video_id": "yRRvHm4so68",
  "title": "Some Title",
  "channel_id": "UCjVXOgEZavu2h4Qt8mK1ZiQ",
  "channel_name": "Example Channel",
  "upload_date": "2025-09-15T11:01:43+00:00",
  "url": "https://www.youtube.com/watch?v=yRRvHm4so68",
  "duration_seconds": 3537,
  "view_count": 10221,
  "subscriber_count": 19500,
  "language": "zh",
  "transcript_lang_source": "default",
  "transcript": []
}

---

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: [].
• 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.