YouTube Search Scraper - Videos, Views, Channels

Search YouTube keywords and export supported primary video results: title, displayed views, relative publish date, duration, channel name, URL and ID, verified badge, description snippet and encounter order. No user-supplied YouTube API key is needed. This Actor does not consume your YouTube Data API quota, but it is not unlimited: YouTube can block, throttle, change layouts or end pagination early.

Price: $1 per 1,000 videos ($0.001 per video). Videos filtered out by minViews are not charged.

What is collected

Only videoRenderer cards in recognized primary search containers are parsed, including supported item sections, rich-item wrappers and continuation layouts. Recommendation shelves (such as “People also watched”), Shorts shelves, secondary columns and ad/promotion containers are excluded. A Short may appear if YouTube serves it as a regular primary video card. Unsupported primary layouts are reported as extraction failures, not as proof of no results.

rank is the one-based encounter order of unique supported primary videos, before the local minViews filter. It can have gaps after filtering. It is not an exact YouTube SERP position or an SEO ranking measurement: excluded cards do not count, and results can vary with region, time, source corrections and source behavior. Continuation requests use the WEB client with hl=en and gl=US; this is not a guarantee of localized search results.

Duplicates of a video ID within one query are delivered only once, including within a page. The same video appearing in two different queries is a separate query-result row and is charged in each query. Duplicate normalized input queries run once.

Output example

Illustrative row (not a promise of current video statistics):

{
  "searchQuery": "iphone 17 review",
  "rank": 1,
  "videoId": "rng_yUSwrgU",
  "url": "https://www.youtube.com/watch?v=rng_yUSwrgU",
  "title": "iPhone 17 Review: No Asterisks!",
  "viewsText": "6,811,291 views",
  "views": 6811291,
  "publishedText": "11 months ago",
  "duration": "11:20",
  "durationSeconds": 680,
  "isLive": false,
  "channelName": "Marques Brownlee",
  "channelId": "UCBJycsmduvYEL83R_U4JriQ",
  "channelUrl": "https://www.youtube.com/@mkbhd",
  "channelVerified": true,
  "descriptionSnippet": "...",
  "thumbnailUrl": "https://i.ytimg.com/vi/rng_yUSwrgU/hq720.jpg",
  "scrapedAt": "2026-09-24T00:00:00+00:00"
}

Fields	Meaning / availability
searchQuery, videoId, url	Requested normalized query and stable video identity/link.
rank, scrapedAt	Unique primary encounter order and UTC extraction timestamp.
title, descriptionSnippet	Displayed text; null if absent. Not the full description.
viewsText, views	Displayed text and parsed count, potentially rounded or null. Live cards can show concurrent viewers instead of cumulative views.
publishedText	Source relative date, not a verified publication timestamp. Null if absent.
duration, durationSeconds	Displayed duration and parsed seconds; null if absent/live.
isLive, channelVerified	Inferred from the returned card, not independent verification.
channelName, channelId, channelUrl, thumbnailUrl	Card metadata, nullable.

Input

Field	Description
searchQueries	Array of nonblank strings. Omit this field ({}) to run demo iphone 17 review. Explicit null, empty array, blank string or any blank/invalid array member fails without demo or result charges. The runtime also accepts one nonblank string.
maxResultsPerQuery	Integer 1–500, default 50. Requested delivery cap, not a guarantee of 500 results. Invalid values fail rather than being silently clamped.
uploadDate	any, hour, today, week, month, year; default any. Passed to YouTube, not independently verified against video publication timestamps.
sortBy	relevance, views, rating; default relevance. Only combinations in the table below are supported.
minViews	Nonnegative integer, default 0. Local filter on displayed/parsed views. With a positive threshold, missing counts are skipped.

Sort	Supported upload dates
relevance	any, hour, today, week, month, year
views	any, today, week, month, year (not hour)
rating	any only

Unsupported combinations and unknown/null option values fail with a clear OUTPUT error before any search or result charge. They are never silently substituted. effectiveFilters records the accepted date, sort, minimum views, type=video and the exact sp sent; this describes requested source filters, not independent proof YouTube honored them.

{
  "searchQueries": ["air fryer recipes"],
  "maxResultsPerQuery": 80,
  "uploadDate": "week",
  "sortBy": "views",
  "minViews": 1000
}

Coverage and OUTPUT

Dataset rows are saved incrementally. The OUTPUT key-value record is written on normal completion and before propagating input, billing or extraction errors. It includes:

• queries, scraped, perQuery: normalized query count, actual delivered/charged row count and counts per query (including zero for unstarted queries).
• demoUsed, effectiveFilters: available after successful input validation.
• status: complete, limited, partial or error.
• failed: queries with extraction/request failures or safety truncation; chargeLimitReached: SDK budget stop.
• queryResults[query]: scraped, pages, scannedVideos (including repeated cards), uniqueVideos, effectiveFilters, coverage, stopReason, error.
• Top-level error and errorType when an exception propagates. Invalid input has no accepted per-query filters/results.

coverage	stopReason	Interpretation
complete	exhausted	Supported primary results ended without another continuation. This does not mean every matching YouTube video was available.
limited	max_results	Requested result cap reached; no claim of source exhaustion.
limited	charge_limit	SDK budget limit reached; only its accepted prefix was delivered.
not_started	charge_limit / not_started	Query not attempted due to budget or an earlier fatal error.
partial / unavailable	missing_config	More results exist, but initial HTML lacked the key/client version required for continuation.
partial / unavailable	invalid_initial_json / invalid_continuation_json / invalid_layout	Missing, malformed or unsupported source payload.
partial / unavailable	request_failed	Request retries failed or access was blocked.
partial	repeated_token / page_limit / scan_limit	Loop protection or safety ceiling prevented further coverage.
partial / unavailable	unexpected_error	Unexpected parsing/runtime or billing error; run fails rather than hiding it.

Pagination continues through empty or duplicate-only pages when a new token exists. Each query is capped at 100 pages and 1,000 scanned video cards, including duplicates; unprocessed data or a remaining continuation at a ceiling is reported explicitly. A missing continuation after a recognized empty result list is a valid no-match outcome, not a reason to switch to demo data.

Partial rows survive later request/JSON failures, with diagnostics in OUTPUT. Such runs can succeed with status=partial; consumers must inspect coverage, not just platform status. If no rows were delivered and any query failed or hit a safety ceiling, the Actor fails after writing OUTPUT. Billing failures propagate even if earlier rows were delivered.

Use cases

• Keyword/content research using supported primary cards and their displayed metrics.
• Trend discovery using week + views, subject to source ordering and approximate dates.
• Channel discovery; enrich returned channel IDs with a separate channel scraper.
• Scheduled brand/competitor keyword searches, with coverage checks on each run.

Pricing

Pay per event: $0.001 per video plus the standard Apify actor-start fee. Delivery and the video event use one atomic SDK operation; its chargeable prefix determines both rows and counters. A run budget stops further delivery when the SDK signals its limit. Result-event tests do not imply zero total cost for empty/invalid runs or certify cloud pricing.

FAQ / troubleshooting

Can I always get 500 results? No. 500 is an input cap, not a measured source guarantee. Filters, budget, upstream availability and safety ceilings can yield fewer. Check each query's stopReason.

Does no API quota mean unlimited scraping? No. No user API key/quota is required, but request limits, anti-bot checks and Actor budgets still apply.

Can I track exact SEO ranks? No. rank is supported unique-video encounter order only.

Why are dates relative? These are YouTube's display strings. Date filters are passed to YouTube; the Actor does not verify precise publication dates.

Can I combine hour + views or week + rating? No. Use a supported combination; unsupported combinations fail explicitly.

Why did a successful run return fewer rows? Inspect OUTPUT.queryResults: exhausted, requested cap, budget, extraction errors and safety stops are distinct. Retry transient failures; changed layouts may require a parser update.

Local regression tests

From the Actor directory run python -B -m unittest -v test_main with its dependencies installed. The suite executes main() using synthetic HTTP and Actor/budget stubs and blocks socket connections. It verifies the local delivery contract, not current YouTube availability or real cloud billing.

Only public data is collected. Use it in compliance with YouTube's terms and applicable laws.