YouTube Video Scraper

The Actor collects full metadata for a list of public YouTube videos and Shorts, and can attach four optional extras to each one: related content, a timed transcript, a caption track in a chosen language, and other Shorts using the same sound. Videos are accepted as URLs or bare IDs. No YouTube account, API key, or cookie is required.

Accepted input

Field	Type	Default	Description
video_sources	array	—	Required. Video or Shorts URLs, or bare 11-character IDs.
video_kind	enum	auto	auto detects Shorts from the URL, video and shorts force one endpoint.
maxItems	integer	100	Maximum videos processed. 0 processes every supplied target.
region_code	string	US	Two-letter country code used to localize results.
language_code	string	en	Language code for result text and transcript selection.

Optional enrichment, each charged only on success:

Field	Type	Default	Description
includeRelatedContent	boolean	false	Attaches related videos and playlists.
includeTranscript	boolean	false	Attaches the timed transcript when one exists.
includeCaption	boolean	false	Attaches one caption track as text.
caption_language	string	en	Language code of the caption track to attach.
caption_translation	string	—	Language code to translate the chosen caption into.
includeSoundShorts	boolean	false	For Shorts, attaches other Shorts using the same sound.
maxRelatedItems	integer	20	Cap on related or same-sound items per video. 0 collects every page.

{
  "video_sources": [
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
    { "url": "https://youtu.be/9bZkp7q19f0" },
    { "url": "kJQP7kiw5Fk" }
  ],
  "video_kind": "auto",
  "includeTranscript": true,
  "maxItems": 100
}

Response fields

One row per video.

Field	Contents
recordType	video_details or short_details
source	The URL or ID as supplied
id, videoId	Video ID
title, description	Video text
url	Canonical URL, derived from the ID
channelId, channelTitle, channelHandle	Publishing channel
viewCount, likeCount, commentCount	Reported counts
lengthSeconds	Duration in seconds
publishedAt, publishDate	ISO 8601 timestamp and date
category	YouTube category
keywords	Public tags declared on the video
isLiveContent	Whether the video is or was live
hasCaption	Whether YouTube reports a caption track
availableCountries	Countries the video is playable in
soundAttribution	Sound credited on a Short
thumbnail	Thumbnail images

Present only when the matching enrichment is enabled:

Field	Contents
transcript	Timed segments, plus the language menu YouTube offers
caption	The selected track's language, and its text
related	Related videos and playlists
soundShorts	Other Shorts using the same sound

{
  "recordType": "video_details",
  "id": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "channelTitle": "Rick Astley",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "viewCount": "1798246481",
  "lengthSeconds": "213",
  "isLiveContent": false,
  "hasCaption": true
}

A transcript is returned as timed segments rather than a wall of text:

{
  "transcript": [
    { "startMs": "320", "endMs": "14580", "startTime": "0:00", "text": "[Music]" }
  ]
}

Transcripts and captions

The two are different things and are charged differently.

includeTranscript returns YouTube's timed transcript for the video — the same one the transcript panel shows — as segments with start and end times. It is one request per video.

includeCaption returns a caption track as text in a chosen language. It is two requests per video: one to list the available tracks, and one to fetch the chosen one. If caption_language is not among the tracks YouTube offers, a warning names the missing language and the video is still saved without a caption, uncharged. caption_translation asks YouTube to translate the chosen track, and the available translation languages are extensive — over 120 for a widely watched video.

Both are attached per video and both are optional. Transcript availability is a property of the video: a video with hasCaption: false has no transcript to return, and asking for one costs nothing.

Behaviour on partial results

Each video is fetched individually. A target that cannot be parsed, or that YouTube declines to return, is logged and skipped, and the run continues with the rest. The run fails only when no supplied target was a usable video reference.

Fetching in batches was tested and is not used. The endpoint accepts several IDs at once, but a single unavailable video makes the whole batch fail — and which videos do this is not predictable from fetching them individually. One request per video costs more requests and loses nothing when one video is bad.

The four enrichments are independent. Each is attempted separately, and a failure leaves that one field absent, is not charged, does not affect the others, and does not interrupt the run. Enabling all four performs up to five extra requests per video, so a 500-video run with everything enabled is a large run — enable them on a shortlist rather than on a first pass.

Frequently asked questions

Which URL forms are accepted? youtube.com/watch?v=, youtu.be/, youtube.com/shorts/, /embed/, and /live/, plus bare 11-character video IDs. Mixing forms in one run is fine.

When should video_kind be set rather than left on auto? auto identifies a Short from a /shorts/ URL. A Short supplied as a bare ID or a watch?v= link is not distinguishable from a regular video, so it is fetched through the video endpoint — which works and returns the standard metadata, but not soundAttribution. Set video_kind: "shorts" when the whole list is Shorts and those fields matter.

Why did includeSoundShorts produce nothing? It applies only to targets treated as Shorts. If a Short was supplied as a bare ID with video_kind: "auto", it was fetched as a regular video and the same-sound lookup was skipped. Setting video_kind: "shorts" resolves it.

Is viewCount live? It is the count YouTube reports at the moment of the request. YouTube itself delays and rounds view counts on recently published videos, so a figure for a video minutes old is provisional.

Why is likeCount missing on some videos? Creators can hide the like count, and YouTube then omits it rather than returning zero. Absent means hidden or unreported; it does not mean no likes.

Does maxRelatedItems count towards maxItems? No. maxItems bounds how many videos are processed; maxRelatedItems bounds the related or same-sound rows attached to each one. They are separate budgets.

Is a YouTube account or API key required? No. Only publicly visible videos are read, with no credentials or logged-in session, and no YouTube Data API quota is consumed.

Related Actors

Actor	Purpose
YouTube Search Scraper	Find videos by keyword, hashtag, or chart
YouTube Channel Scraper	Everything a channel publishes
YouTube Comments Scraper	Comments from videos, Shorts, and community posts
YouTube Playlist Scraper	Playlist metadata and every video in it