YouTube Search Results Scraper - Videos & Channels

Export public YouTube search-card results for known keywords, including videos, Shorts, live or upcoming videos, channels and playlists. Retain query provenance, filtered result order, public source fields and collection time. Localization and native filters request a search context rather than universal rankings or complete YouTube coverage.

Quick start

Choose one focused query and a small per-query cap before expanding filters or locales. The existing example combines two queries with video, upload-date and duration filters:

{
  "queries": ["web scraping tutorial", "Apify automation"],
  "maxResultsPerQuery": 25,
  "resultType": "videos",
  "sortBy": "uploadDate",
  "uploadDate": "month",
  "duration": "medium",
  "country": "US",
  "language": "en",
  "connectionMode": "automatic"
}

Prefer a video guide? This short Apify walkthrough shows you how to set up and run an Actor. It uses a different Actor, but the setup steps are the same.

Ready-to-run examples

Choose a small preconfigured example:

• Find YouTube videos for content research — collect video search cards for a topic sample.
• Discover YouTube channels by keyword — find matching public channels and available channel metadata.
• Find YouTube playlists by topic — retrieve playlist search cards without expanding their videos.

What you get

One unique retained search-result row with query, result type, title, source URL, available identity and search-card metadata. Rank restarts per query after filtering and deduplication, while page and positionOnPage retain response context. Counts and duration can have both displayed text and parsed values, with missing fields left unknown.

Who is it for?

• Content researchers reviewing bounded video and playlist topic samples.
• YouTube SEO analysts storing observed keyword and locale snapshots.
• Creator researchers inspecting public channel candidates and source context.
• Data developers routing known result IDs into separate detail or transcript workflows.

Input settings

Setting	JSON field	Description
Search queries	queries	One to 50 non-empty keywords or phrases. Blank rows are ignored and duplicate queries run once.
Results per query	maxResultsPerQuery	Save 1-500 unique matching rows per query.
Result type	resultType	Mixed results, videos (including Shorts/live), channels, or playlists.
Sort	sortBy	Relevance, rating, upload date, or view count.
Upload date	uploadDate	Any time, hour, today, week, month, or year.
Duration	duration	Any, under 4 minutes, 4-20 minutes, or over 20 minutes.
Video feature	videoFeature	Any, live, HD, subtitles/CC, or Creative Commons.
Country	country	Optional two-letter localization code such as US, GB, PT, or DE.
Language	language	Optional code such as en, pt, de, or en-GB.
Raw filter token	sp	Advanced token copied from a YouTube search URL. When set, it overrides the structured YouTube filters.
Connection	connectionMode	Direct or Automatic. See field help for proxy costs and advanced settings.
Advanced controls	proxyConfiguration, retryCount, initialRetryDelayMillis, requestPacingMillis, runTimeSecs	Optional proxy, retry, pacing and work-time settings. See field help.

YouTube decides which filter combinations it supports. A raw sp token is kept for backward compatibility and advanced combinations that are not represented by the structured fields.

Output data

The existing synthetic row illustrates field shape rather than an actual current ranking:

{
  "query": "web scraping tutorial",
  "rank": 1,
  "resultType": "video",
  "title": "Web scraping tutorial",
  "url": "https://www.youtube.com/watch?v=example",
  "videoId": "example",
  "channelId": "UCexample",
  "playlistId": null,
  "channelName": "Example Channel",
  "channelUrl": "https://www.youtube.com/@example",
  "publishedTimeText": "2 weeks ago",
  "durationText": "12:34",
  "durationSeconds": 754,
  "viewCountText": "10K views",
  "viewCount": 10000,
  "subscriberCountText": null,
  "subscriberCount": null,
  "videoCountText": null,
  "videoCount": null,
  "descriptionSnippet": "A visible public search-result snippet...",
  "thumbnailUrl": "https://i.ytimg.com/vi/example/hq720.jpg",
  "thumbnailUrls": ["https://i.ytimg.com/vi/example/hq720.jpg"],
  "isShort": false,
  "isLive": false,
  "isUpcoming": false,
  "badges": [],
  "searchUrl": "https://www.youtube.com/results?search_query=web+scraping+tutorial",
  "page": 1,
  "positionOnPage": 1,
  "resultKey": "video:example",
  "scrapedAt": "2026-07-14T12:00:00.000Z"
}

Download results as JSON, CSV, Excel, XML, or RSS, or consume them through the Apify API and MCP server. RUN_SUMMARY in the run's key-value store records each query's status, pages, retries, saved rows, recognized empty results, partial failures, and deadline state.

Field group	Fields	Description
Search provenance	query, rank, searchUrl, page, positionOnPage, resultKey, scrapedAt	Where and when the unique row appeared.
Identity	resultType, title, url, videoId, channelId, playlistId	Public result type, label, link, and identifiers.
Channel	channelName, channelUrl	Visible creator/channel attribution.
Time and counts	publishedTimeText, durationSeconds, viewCount, subscriberCount, videoCount and their text fields	Source-visible text and parsed values when available.
Content signals	descriptionSnippet, isShort, isLive, isUpcoming, badges	Public search-card context and classifications.
Images	thumbnailUrl, thumbnailUrls	Best and all visible thumbnail URLs.

Download your results

Open your run's dataset, choose Export and select JSON, CSV or Excel. JSON keeps nested fields together. CSV and Excel are useful when you want to review the records in a spreadsheet.

See Apify's download and export guide for the available formats and field options.

Pricing

After input validation and a budget/deadline preflight, each run has a start event. If your remaining cost allowance cannot cover startup plus one result, or fewer than 17 seconds remain, the Actor stops successfully before that start charge or any search. Each saved result row has a coupled result event. Recognized empty or fully filtered queries have no result-row charges, while the start event still applies to the valid run.

See the live Pricing tab for current rates and tier discounts. Platform compute, storage, proxies or transfer can also apply.

Tips for best results

• Start with one query and a low cap. Review titles, snippets and source links before expanding your topic sample.
• Keep the search context. Store locale, filters, rank and scrapedAt to compare your own snapshots. Comparison and alerts belong in your downstream workflow.
• Use IDs for follow-up collection. Pass returned video or playlist URLs to a related detail or playlist Actor when you need more than a search card.
• Check the summary before analysis. Separate completed searches from partial or failed queries before interpreting a smaller dataset.

Limits and caveats

• Search cards, not full details. The Actor does not collect comments, transcripts, likes or exact publication timestamps. Channel rows do not enumerate a channel catalog, and playlist rows do not expand membership.
• Rank is a snapshot. YouTube can localize, reorder and vary results. Filtered rank is not a universal position or proof of complete coverage.
• Some searches return no rows. Supported no-match, fully filtered or explicitly sign-in/age-restricted searches complete empty with a reason in RUN_SUMMARY. The Actor does not log in to YouTube.
• Partial results need review. Query failures, charge limits and the work deadline can leave incomplete results. Already saved rows remain available, and every query has a summary outcome. Expected customer cost/timeout stops succeed with a warning and a limitStop reason in RUN_SUMMARY; they are not no-match searches. Genuine network, parser, storage and billing failures remain failures.
• Unexpected blocking is not an empty-search guarantee. Unrecognized responses and source errors remain actionable failures even when another query returns useful rows.
• Missing fields stay unknown. Counts, snippets and relative publish text reflect what the search card exposes.

Automation and integrations

Save your settings for next time

Once you have an input that works for you, save it as an Apify task. This keeps your settings together so you can use them again without filling in the form from scratch.

Run on a schedule

Need fresh results regularly? You can schedule the Actor or a saved task to run at a time that suits you.

Each scheduled run collects the data again. If you want to compare results or highlight changes, add that step in your own workflow.

Send results to your other tools

Use n8n, Make or Zapier to connect this scraper to the rest of your workflow. For example, you could pass its results to an AI assistant or add records to a spreadsheet. Follow the Apify integration guides for your chosen tool.

For a custom connection, an Apify webhook can notify your app when a run finishes or fails. Your app can then fetch the results or handle the failure.

API usage

Want to collect this data from your own app or automation? The examples below send input to the scraper and show how to collect its results.

The Node.js and Python examples wait for the run to finish before reading its results. The cURL example starts the run and returns its details. Wait for that run to finish, then use its defaultDatasetId to fetch the results.

For setup instructions, see Apify's JavaScript client guide, Python client guide and Actor runs API reference.

cURL

curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~youtube-search-results-scraper/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"queries":["web scraping tutorial"],"maxResultsPerQuery":25,"resultType":"videos","country":"US","language":"en"}'

Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/youtube-search-results-scraper').call({
  queries: ['web scraping tutorial'],
  maxResultsPerQuery: 25,
  resultType: 'videos',
  country: 'US',
  language: 'en',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')
run = client.actor('fetch_cat/youtube-search-results-scraper').call(run_input={
    'queries': ['web scraping tutorial'],
    'maxResultsPerQuery': 25,
    'resultType': 'videos',
    'country': 'US',
    'language': 'en',
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

MCP and AI agents

You can ask your AI assistant to collect data with YouTube Search Results Scraper and help you work with the results. The scraper returns the data, and your assistant can then summarize it, compare records or prepare notes.

Connect your assistant through the Apify MCP server. MCP gives your assistant a way to find this scraper, run it and read the results. Follow the official setup and sign-in guide for your app.

Easier setup with an Apify plugin

If you use a supported coding assistant, the official Apify plugin can set up the connection for you. It connects your assistant to Apify and includes instructions for common tasks. Follow the guide for your particular app.

Use Apify AI in Console

Prefer to keep everything in Apify? Open Apify AI in Console and ask it to find Fetch Cat's YouTube Search Results Scraper. You can describe the data you want and ask questions about the results.

Apify AI is currently in beta. It asks for confirmation before starting an Actor, and normal run charges apply.

Choose your assistant

• Claude and Claude Code (Anthropic): Apify setup guide.
• ChatGPT and Codex (OpenAI): Apify setup guides.
• Grok Bot (xAI): Apify plugin guide.
• Gemini CLI (Google): MCP server setup guide. Use the server URL below with the HTTP configuration supported by Gemini CLI.

Connect just this scraper

To keep your setup focused on this scraper, add this server configuration to a compatible MCP client:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=fetch_cat/youtube-search-results-scraper"
    }
  }
}

Sign in to Apify when your client asks. If your client uses a Bearer token instead, follow its setup guide and keep the token in its secure configuration. Configuration formats vary by app, so use the linked guide if your client needs a different format.

Use Apify's general server

Already connected to the general Apify MCP server at https://mcp.apify.com? You can use it to find this scraper without adding another server. Ask your assistant to use YouTube Search Results Scraper by Fetch Cat, or give it the identifier fetch_cat/youtube-search-results-scraper.

Your assistant can check the available settings and retrieve the results from the returned run. If the run is still working, it should follow that run rather than start it again. Both connection options use Apify's hosted service.

Example requests

• “Find five English-language YouTube videos about web scraping tutorials using US search settings. Show me their titles, channels and links.”
• “Find five YouTube channels matching Apify automation. Put their names, links and available subscriber counts in a comparison table.”
• “Find three playlists about web scraping tutorials. Give me their titles and links so I can choose one to explore separately.”

Normal Apify charges apply. Check the live Pricing tab before asking your assistant to run a larger batch.

Pay with x402

If your AI agent has a funded wallet, it can pay for Apify usage through x402. This experimental option lets an agent use Apify without a conventional account.

Apify AGI provides a prepaid API token with a spending cap after payment. Your agent can use that token to run this scraper through the Apify API or an authenticated MCP connection.

Some MCP setups also support paying for each request directly. That is a different payment option, so check the official guide for its availability.

Follow the official guide for wallet setup, supported payment options and current terms. Apify handles the payments. Keep wallet keys and payment tokens in your agent's secure configuration.

Other ways for agents to pay

Apify also supports MPP for prepaid access through AGI and Skyfire for eligible Actors. If your agent already uses one of these, see the agentic payment guide to choose the right setup.

FAQ

Why did I receive fewer rows than maxResultsPerQuery?

That value is a maximum. YouTube may expose fewer public matches for a filter/locale, return duplicates across continuation pages, or stop offering continuation data. Check RUN_SUMMARY for saved, filtered, duplicate, retry, empty, partial, and deadline details.

Is a zero-row run always an error?

No. A recognized valid search with no matches finishes as EMPTY_FILTERED and does not charge result events. Unexpected layouts, unrecognized blocking responses or all-query request failures fail the run. Recognized search-specific sign-in restrictions instead report SIGN_IN_REQUIRED with no rows for that query, as described in Limits and caveats.

Can it collect comments, transcripts, or full video details?

This Actor stays focused on fast public search results. Use a related Actor for detail-page, transcript, comment, channel-catalog, playlist-video, or Shorts-specific collection.

Do country and language guarantee identical results for every user?

No. They request a locale from YouTube, but public results can still change with time, source response, personalization experiments, and availability.

Related Actors

• YouTube Video Details Scraper — enrich known video URLs or IDs.
• YouTube Transcript Scraper — export available video transcripts.
• YouTube Comments Scraper — collect public video comments.
• YouTube Channel Videos Scraper — Collect recent public YouTube channel video metadata, without promising a complete historical archive.
• YouTube Shorts Scraper — Collect metadata for available public YouTube Shorts.
• YouTube Playlist Videos Scraper — expand known playlists into video rows.

Support and feedback

For custom additions or integrations, email hello@fetchcat.dev.

Found an error or have a feature request? Open an issue with the run URL, a non-sensitive input example and what you expected.

Need help sharing it? See Apify’s guide to sharing a run when reporting an issue. Sharing a run can give the developer access to its input, logs and results, so use a run that contains no sensitive data. Please leave out API tokens, passwords, cookies, private documents and personal data. Use a public sample URL or a redacted example instead.

Tried this scraper? We'd love to hear how it worked for you. Leave a review to help others choose the right tool and help us improve it. Your feedback means a lot to us.

Made with care for curious people, AI agents and the possibilities in data. ♥