YouTube Scraper

Scrape YouTube videos by search keyword or by channel (URL, @handle, or UC… id) using YouTube's internal InnerTube (youtubei/v1) JSON API. No API key, no cookies, no login. Auto-paginates via continuation tokens to reach your requested item count.

For every video it returns: videoId, title, watch url, channelName, channelId, viewCountText, publishedTimeText, lengthText, and the largest thumbnail.

What it does

• Search mode — give one or more keywords; each query returns up to maxItems matching videos.
• Channel mode — give one or more channels; each returns up to maxItems of its newest videos.

You can use either mode or both in a single run. Results are de-duplicated by videoId across all queries and channels, so you never pay for the same video twice in one run.

Input

Field	Type	Description
searchQueries	string[]	Keywords to search, one per line. Optional if you supply channelUrls.
channelUrls	string[]	Channel URLs, @handles, or raw UC… ids. Optional if you supply searchQueries.
maxItems	integer	Max videos per query and per channel (1–1000, default 50).
proxyConfiguration	object	Proxy for all requests. Residential Apify Proxy is strongly recommended — YouTube blocks datacenter/cloud IPs aggressively.

You must provide at least one of searchQueries or channelUrls. If both are empty the actor pushes an uncharged BAD_INPUT diagnostic row (it does not crash).

Example input

{
  "searchQueries": ["lofi hip hop", "python tutorial"],
  "channelUrls": ["https://www.youtube.com/@LofiGirl", "UCSJ4gkVC6NrvII8umztf0Ow"],
  "maxItems": 50,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

Output

Each successful video is one dataset row with ok: true:

{
  "ok": true,
  "videoId": "n61ULEU7CO0",
  "title": "lofi hip hop radio - beats to relax/study to",
  "url": "https://www.youtube.com/watch?v=n61ULEU7CO0",
  "channelName": "Lofi Girl",
  "channelId": "UCSJ4gkVC6NrvII8umztf0Ow",
  "viewCountText": "123,456 views",
  "publishedTimeText": "2 years ago",
  "lengthText": "1:02:33",
  "thumbnail": "https://i.ytimg.com/vi/n61ULEU7CO0/hqdefault.jpg",
  "mode": "search"
}

Nullable / empty fields

YouTube's modern channel grid uses a different layout than search results, so a few fields can come back as an empty string "" depending on which layout a video uses:

• channelId — may be empty for some channel-grid videos (the grid layout does not always carry the id).
• viewCountText, publishedTimeText, lengthText — may be empty for live streams, premieres, or radio-style "videos" that have no view count or fixed duration.
• thumbnail — falls back to https://i.ytimg.com/vi/<videoId>/hqdefault.jpg if no source URL is present, so it is rarely empty.

videoId, title, and url are always present on ok: true rows.

Pricing

This actor charges per returned video (pay-per-result). You are charged only for genuine ok: true video rows.

• Blocked, rate-limited, network-error, and empty (NO_RESULTS) runs are never charged. When something goes wrong the actor pushes an ok: false diagnostic row with an errorCode instead of charging you.

Diagnostics

On any failure the actor pushes a diagnostic row (ok: false) carrying a clear errorCode rather than silently returning nothing:

errorCode	Meaning
BAD_INPUT	No searchQueries or channelUrls were provided.
BLOCKED	YouTube blocked the request (anti-bot / 403). Use a residential proxy.
RATE_LIMITED	Hit a 429. The actor backed off and retried; lower volume or add a proxy.
SERVER_ERROR	YouTube returned a 5xx. Usually transient — retry later.
NO_RESULTS	The request succeeded but matched no videos for your input.
NETWORK	A network error reaching YouTube.

Troubleshooting

• Got NO_RESULTS or BLOCKED for a channel you know has videos? YouTube blocks cloud/datacenter IPs aggressively. Enable Apify Proxy with the RESIDENTIAL group and re-run — this resolves the large majority of empty/blocked results.
• RATE_LIMITED on large runs? A high maxItems (toward 1000) requires many paginated requests. Lower maxItems, run fewer queries per run, or keep the residential proxy on.
• Channel won't resolve (BAD_INPUT: could not resolve channel)? Double-check the handle/URL, or pass the raw UC… channel id directly.