YouTube Search Scraper — Videos, Channels, Playlists & Filters

Use this Apify Actor when you need structured YouTube search results from one or more free-text queries. It accepts terms exactly as they would be typed into the YouTube search bar, and returns one normalized record per search result in a dataset row. Each row can include the result type, query, source, rank, IDs, title, canonical URL, channel details, view counts, publish timing, duration, thumbnails, descriptions, badges, and the scrape timestamp. The Actor is usable through Apify MCP and is designed for workflows that turn YouTube search into structured data.

Best fit and connected workflows

This Actor fits workflows that start with a topic, keyword list, or market question and end with structured YouTube search results. Common routes include content research, channel discovery, competitive monitoring, trend scanning, and agent-driven search summaries.

A practical workflow looks like this:

• start with one or more search queries
• narrow by result type, date, duration, or feature filters when you want a focused slice
• read the dataset as one row per result
• pass the structured rows into spreadsheets, databases, dashboards, or AI workflows

It also works through Apify MCP, where an agent can search YouTube and consume the results as structured data.

Practical scenario

Maya, a content strategist, starts with the search query react tutorial 2025 and sets resultType to video, sortBy to viewCount, and maxResultsPerQuery to 25. The dataset returns rows with fields such as title, channelName, viewCountText, publishedTimeText, durationText, and url. Maya uses those fields to identify which videos are surfacing for the query and then decides which channels to track in the next weekly review.

Input

Field	Type	Default	Description
searchQueries	array[string]	required	One or more free-text YouTube search terms. Each query is scraped independently and merged into one dataset.
maxResultsPerQuery	integer	50	Maximum number of results to return for each query across pagination. Applies per query.
resultType	string	all	Restrict results to all, video, channel, playlist, or movie.
sortBy	string	relevance	Use YouTube-style ordering: relevance, uploadDate, viewCount, or rating.
uploadDate	string	any	Filter videos by lastHour, today, thisWeek, thisMonth, or thisYear.
duration	string	any	Filter videos by short, medium, or long.
features	array[string]	[]	Optional feature filters such as live, fourK, hd, subtitles, creativeCommons, threeSixty, vr180, threeD, hdr, location, and purchased.
country	string	US	YouTube geo context (gl) and proxy country.
language	string	en	YouTube interface/content language (hl).
rawSpToken	string	empty	Advanced override for a raw YouTube sp filter token.
fallbackMode	string	auto	Controls when managed fallback engages: auto, never, or always.
proxyConfiguration	object	residential	Proxy settings for the direct HTTP scrape. Residential proxies are the default.

Example input

{
  "searchQueries": ["lofi hip hop", "react tutorial 2025"],
  "maxResultsPerQuery": 25,
  "resultType": "video",
  "sortBy": "viewCount",
  "uploadDate": "thisYear",
  "duration": "medium",
  "features": ["hd", "subtitles"],
  "country": "US",
  "language": "en",
  "fallbackMode": "auto"
}

Output

The default dataset contains one normalized YouTube search result per row. The main fields are stable across result types, with some fields populated only for videos, channels, or playlists.

Field	Type	Description
type	string	Result kind: video, channel, playlist, or movie.
query	string	The search query that produced the result.
source	string	youtube for direct scrape, managed-fallback for managed fallback.
position	integer	1-based rank within the query.
videoId	string or null	YouTube video ID for video and movie results.
playlistId	string or null	YouTube playlist ID for playlist results.
channelId	string or null	Channel ID for the owner or channel result.
title	string or null	Result title.
url	string or null	Canonical URL to the result.
channelName	string or null	Owning channel display name.
channelUrl	string or null	Owning channel URL.
viewCount	integer or null	Parsed numeric view count.
viewCountText	string or null	Raw view count text as shown by YouTube.
publishedTimeText	string or null	Relative publish time text.
durationText	string or null	Video duration text.
durationSeconds	integer or null	Video duration in seconds.
thumbnailUrl	string or null	Highest-resolution thumbnail URL available.
description	string or null	Short description snippet.
isLive	boolean	True when the result is a live broadcast.
isVerified	boolean	True when the channel or owner has a verified badge.
badges	array[string]	Additional badges such as New, CC, or 4K.
subscriberCountText	string or null	Subscriber count text for channel results.
videoCountText	string or null	Video count text for channel or playlist results.
playlistVideoCount	integer or null	Number of videos in a playlist result.
scrapedAt	string	ISO 8601 timestamp of the scrape.

Example record

{
  "type": "video",
  "query": "how to bake sourdough",
  "source": "youtube",
  "position": 1,
  "videoId": "dQw4w9WgXcQ",
  "playlistId": null,
  "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx",
  "title": "Beginner Sourdough Bread Recipe",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "channelName": "The Bread Code",
  "channelUrl": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx",
  "viewCount": 1200000,
  "viewCountText": "1.2M views",
  "publishedTimeText": "2 years ago",
  "durationText": "12:34",
  "durationSeconds": 754,
  "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hq720.jpg",
  "description": "The simplest no-knead sourdough loaf...",
  "isLive": false,
  "isVerified": true,
  "badges": ["CC"],
  "subscriberCountText": null,
  "videoCountText": null,
  "playlistVideoCount": null,
  "scrapedAt": "2026-05-30T12:00:00.000Z"
}

How it works

The Actor uses direct HTTP scraping over residential proxies as its primary path. It parses YouTube search results, supports query-level filtering, and returns a normalized dataset. If YouTube returns challenges during direct scraping, the Actor can use a managed fallback depending on fallbackMode.

The filtering controls map to YouTube search behavior:

• resultType narrows the result kind
• sortBy mirrors YouTube ordering options
• uploadDate and duration apply only where video results are present
• features applies one or more YouTube feature filters
• rawSpToken lets advanced users supply a raw sp token directly

The dataset schema includes source, so each row shows whether it came from direct YouTube scraping or from the fallback path.

Pricing

YouTube Search Scraper - Videos, Channels, Playlists & Filters uses Pay per event pricing plus Apify platform usage. The billed events are tied to search results returned, actor start usage, and managed fallback queries when that path is used. Apify platform usage is billed separately according to the active Apify plan and runtime resources.

A simple example: if a run returns fifty search results, those fifty result events are billed, and the actor start event is billed as well. If one query uses the managed fallback, that query adds the fallback event too. For current amounts and the live Pricing tab, check the actor's Pricing section on Apify.

Use with AI agents (MCP)

This Actor is MCP-ready and usable through Apify MCP. The tool exposes YouTube search as a structured workflow where an agent provides search terms and receives normalized results.

Tool description: Search YouTube by free-text query and return structured search results with result type, ranking, channel metadata, timing, and URLs.

Actor identity: khadinakbar/youtube-search-scraper

Search YouTube for "react tutorial 2025" and return the top 10 video results only. Use US geo and English language. Summarize the titles, channels, view counts, publish times, and URLs from the dataset.

Output interpretation:

• type tells you whether a row is a video, channel, playlist, or movie
• source shows whether the row came from youtube or managed-fallback
• position preserves ranking order within each query
• query preserves provenance for multi-query runs
• url is the canonical destination for the result

Provenance and scope:

• searchQueries is the user-provided search text
• query on each row identifies the source query for that row
• source shows the retrieval path used for the row
• maxResultsPerQuery applies per query across pagination

Pagination and cost guidance:

• each returned search result is a billable search-result event
• fallbackMode: auto uses direct scraping first and only falls back when needed
• fallbackMode: always uses managed fallback for every query and bills the fallback event when results are returned

Apify API example

import { ApifyClient } from "apify-client";

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const input = {
  searchQueries: ["lofi hip hop"],
  maxResultsPerQuery: 5,
  resultType: "video",
  sortBy: "relevance",
  country: "US",
  language: "en",
  fallbackMode: "auto",
};

const run = await client.actor("khadinakbar/youtube-search-scraper").call(input);

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Best results and outcome guidance

For the cleanest dataset shape, start with search queries that match the exact topic or phrase you want to study. Use resultType when you want one content class, and add uploadDate, duration, or features when you want a narrower slice of YouTube search.

A few practical patterns:

• use one query per topic when you want separated result sets
• use maxResultsPerQuery to control per-query depth
• set sortBy to viewCount or uploadDate when ranking matters for analysis
• keep country and language aligned with the market you want to inspect
• use rawSpToken when you already copied a filter token from a YouTube search URL

Continue the workflow

• Then use YouTube Shorts Scraper — Titles, Views, Hashtags, Transcripts & Viral Score to continue from YouTube Search Scraper — Videos, Channels, Playlists & Filters discovery into content data for the selected records.
• Then use YouTube to MP3 Downloader to continue Youtube records selected with YouTube Search Scraper — Videos, Channels, Playlists & Filters into a focused media workflow.

Design note

I found that the dataset contract includes source on every row, which makes it straightforward to separate direct YouTube results from managed-fallback results without changing the row shape.

FAQ

Can I search multiple queries in one run?
Yes. Provide an array in searchQueries, and each query is scraped independently before the results are merged into one dataset.

Which result types can this Actor return?
It returns YouTube search results for videos, channels, playlists, and movies.

How do I focus on only videos?
Set resultType to video. You can also combine it with sortBy, uploadDate, duration, and features.

When does managed fallback appear in the output?
When direct scraping needs the fallback path and fallbackMode allows fallback, the source field shows managed-fallback for those rows.

Can I use this in an Apify MCP workflow?
Yes. This Actor is MCP-ready and can be used through Apify MCP with the actor identity khadinakbar/youtube-search-scraper.

Responsible use

This Actor extracts publicly available YouTube search result data. Use the output in ways that respect YouTube's terms, applicable law, and any obligations tied to personal data, copyright, or local privacy rules. Review the source site, your jurisdiction, and your intended use before storing or sharing the data.