YouTube Search Scraper

Collect current YouTube search results without launching a heavyweight browser. The Actor opens YouTube's public search page using the submitted query, locale, type, and sort values; maps the embedded structured results; discovers the current public web-client configuration at runtime; and uses the matching first-party continuation responses for pagination. It rotates internally consistent request profiles and can use a unique authorized proxy session for retries.

What it returns

The dataset contains only complete, deduplicated result records. A record is one of video, short, channel, or playlist and includes its rank, query, search URL, continuation page, title, canonical URL, IDs, channel data, verification status, badges, thumbnails, description, and extraction timestamp. Videos and Shorts additionally include duration, numeric/visible view counts, live/upcoming state, and visible publication text. Channels and playlists include numeric/visible subscriber or video counts and preview fields when YouTube supplies them.

The default key-value store also contains an OUTPUT run summary with the completion status, result count, page count, and dataset write state. It distinguishes EMPTY, PARTIAL, BLOCKED, AUTH_REQUIRED, ACCESS_DENIED, RATE_LIMITED, MALFORMED, input-validation, proxy, and output-write failures without storing query URLs or transport credentials.

Empty strings, nulls, empty objects, and empty arrays are removed recursively. Thumbnail URLs are normalized to stable public paths without expiring query signatures. A genuine no-results search completes successfully with an empty dataset; malformed, blocked, or unexpected responses fail closed.

Input

Field	Default	Description
query	required	YouTube keyword or phrase (up to 500 characters).
maxItems	50	Number of unique results to save, 1–500.
resultType	all	all, video, short, channel, or playlist.
sortBy	relevance	relevance, upload_date, view_count, or rating. Type-specific searches must use relevance because YouTube permits one server-side filter per request.
maxPages	derived from maxItems	Continuation-page safety limit, 1–30.
languageCode / countryCode	en / US	Locale used for search results.
maxRequestRetries	2	Bounded temporary-failure retries, 0–4.
requestTimeoutSecs	30	Per-request timeout, 5–120 seconds.
requestDelayMillis	500	Polite continuation-page delay, 0–10,000 ms.
proxyConfiguration	Not configured	Optional Apify proxy configuration. Requests use direct access unless a proxy is supplied; Residential is a user-selected option, not the default.

Example

{
  "query": "machine learning",
  "maxItems": 25,
  "resultType": "video",
  "sortBy": "relevance",
  "countryCode": "US",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Example output

Each item is a deduplicated result record (abridged):

{"recordType":"youtube_search_result","rank":1,"query":"machine learning","page":1,"resultType":"video","title":"Example video","videoId":"jNQXAC9IVRw","url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","watchUrl":"https://www.youtube.com/watch?v=jNQXAC9IVRw","requestProfile":"chrome-windows","scrapedAt":"2026-08-16T00:00:00.000Z"}

Video and Short records add duration, view-count text, publication text, and live/upcoming flags. Channel and playlist records use their corresponding IDs and count or preview fields when YouTube supplies them.

Cost and limitations

The actor makes one first-party search request per page and can try five browser profiles per page. Continuation pagination stops at maxPages or maxItems. Results, ranking, localization, badges, and visible counts are point-in-time public YouTube observations and can change between runs. Residential Apify Proxy may improve reliability but consumes proxy usage.

Operational notes

• Results are dynamic and depend on YouTube locale, personalization safeguards, and availability at run time.
• Public web-client values are discovered from the current search page and are never written to logs or datasets.
• The Actor validates status code and content type before parsing HTML or JSON, and never stores raw responses.
• Retries are bounded by maxRequestRetries and apply only to transient network errors or HTTP 5xx responses. Blocked, auth-required, access-denied, rate-limited, and malformed responses fail without another request.
• maxPages is a guardrail; an exhausted continuation token ends the run normally after all collected results are saved.
• Each dataset record carries the selected request profile and public search URL as provenance fields.