# YouTube Search Scraper ($0.5/1000 results) (`api-ninja/youtube-search-scraper`) Actor

Extract structured YouTube search results with advanced filtering. Search videos, channels, playlists, shorts, movies, and shows using YouTube API. Fastest YouTube scraper on the market

- **URL**: https://apify.com/api-ninja/youtube-search-scraper.md
- **Developed by:** [API ninja](https://apify.com/api-ninja) (community)
- **Categories:** Developer tools, Social media, Videos
- **Features:** Limited permissions
- **Stats:** 4,167 total users, 916 monthly users, 100.0% runs succeeded, 82 bookmarks
- **User rating**: 4.88 out of 5 stars

## Pricing

from $0.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

**YouTube Search Scraper** turns a YouTube keyword search into a structured dataset of videos, Shorts, channels, playlists, and movies. Use it for **content research, creator discovery, trend monitoring, competitor analysis, lead generation, or building a YouTube search API**—without running a browser or supplying your own YouTube API key.

Enter a search query, choose any filters, and click **Start**. Results are available in the Apify Dataset as JSON, CSV, Excel, XML, or through the API.

### What can YouTube Search Scraper do?

- 🔎 Search YouTube by keyword and collect public result metadata.
- 🎬 Find videos, Shorts, movies, channels, or playlists.
- 🧰 Filter by upload date, duration, country, language, popularity, and video features such as HD, 4K, live, subtitles, Creative Commons, HDR, or VR180.
- 📚 Choose between fast basic results and three deeper video-detail modes.
- ♾️ Set a result limit or continue through all available result pages.
- ⚡ Get results quickly without browser automation or proxy configuration.
- 🔁 Run searches on a schedule, monitor runs, trigger webhooks, and connect the dataset to other apps with [Apify integrations](https://apify.com/integrations).
- 🔌 Use the Actor as a YouTube search API from JavaScript, Python, the Apify CLI, HTTP, OpenAPI, or MCP.

### How to scrape YouTube search results

1. Open [YouTube Search Scraper](https://apify.com/api-ninja/youtube-search-scraper) and click **Try for free**.
2. In **Input**, enter the YouTube keywords you want to search for.
3. Optionally select a result type, detail depth, result limit, sort order, location, language, or video filters.
4. Click **Start** and wait for the run to finish.
5. Open **Dataset** to review the results or export them as JSON, CSV, Excel, or XML.

### Input

Only `query` is required. The smallest valid `maxResults` value is 20.

![Input Schema](https://ik.imagekit.io/vyaz6adho/input.jpg)

```json
{
  "query": "cats",
  "type": "video",
  "videoDepthDetails": "basic",
  "maxResults": 100,
  "scrapeAllResults": false,
  "sortBy": "popularity",
  "duration": "3to20min",
  "uploadDate": "month",
  "geo": "US",
  "lang": "en",
  "features": {
    "HD": true,
    "subtitles": true
  },
  "local": false
}
```

| Field               | Type    | Description                                                                                       |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `query`             | string  | **Required.** Keywords to search for on YouTube.                                                  |
| `type`              | string  | `video`, `channel`, `playlist`, `movie`, or `shorts`. Defaults to `video`.                        |
| `videoDepthDetails` | string  | `basic`, `standard`, `detailed`, or `complete`. Defaults to `basic`. See the depth table below.   |
| `maxResults`        | integer | Maximum number of results to save. Defaults to `100`; ignored when `scrapeAllResults` is enabled. |
| `scrapeAllResults`  | boolean | Continue until YouTube returns no continuation token. Use carefully for broad searches.           |
| `sortBy`            | string  | `relevance` or `popularity`. Sorting is not available for Shorts.                                 |
| `duration`          | string  | `under3min`, `3to20min`, or `over20min`. Applies to video searches.                               |
| `uploadDate`        | string  | `today`, `week`, `month`, or `year`.                                                              |
| `geo`               | string  | Two-letter uppercase country code, for example `US`, `GB`, or `IN`.                               |
| `lang`              | string  | Two-letter lowercase language code, for example `en`, `es`, or `fr`.                              |
| `features`          | object  | Video filters. Enabled filters are combined, so a result must match all selected features.        |
| `local`             | boolean | Request localized YouTube data.                                                                   |

#### Which video detail depth should you use?

| Depth      | Best for                         | Typical data                                                                                                               |
| ---------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `basic`    | Fast search and discovery        | Result type, video ID, title, channel, description snippet, views, publication time, duration, and thumbnails.             |
| `standard` | Analytics and richer exports     | Expanded video and channel information requested in batches, which can include engagement metrics and additional metadata. |
| `detailed` | Technical or compliance research | Per-video extended metadata, such as captions, restrictions, privacy, or availability when YouTube provides it.            |
| `complete` | Maximum available context        | The broadest per-video response, including any additional metadata returned by the upstream service.                       |

Deeper modes make extra requests and therefore take longer. They enrich video and Short results; channel and playlist searches generally use `basic`. YouTube does not expose every field for every item, so treat enriched fields as optional.

### Output example

Each dataset row represents one search result. The exact fields depend on the result type and selected detail depth.

![Output example](https://ik.imagekit.io/vyaz6adho/output.jpg)

```json
{
  "type": "video",
  "videoId": "w2JItRqGbwo",
  "title": "Mama Cat Loves Jewelry but Can’t Afford Any—Ginger Kitten Makes Her a Priceless Necklace 💎🐾",
  "channelTitle": "Ginger's Daily Meow",
  "channelId": "UCCopCDwCZO2ApAHNCiuy6ng",
  "description": "Mama Cat Loves Jewelry but Can't Afford Any—Ginger Kitten Makes Her a Priceless Necklace ...",
  "viewCountText": "223,945 views",
  "viewCount": "223945",
  "publishedTimeText": "1 day ago",
  "publishDate": "2026-01-08",
  "publishedAt": "2026-01-08T00:00:00Z",
  "lengthText": "30:19",
  "thumbnail": [
    {
      "url": "https://i.ytimg.com/vi/w2JItRqGbwo/hq720.jpg",
      "width": 720,
      "height": 404
    }
  ]
}
```

### How much does it cost to scrape YouTube search results?

YouTube Search Scraper uses **pay-per-event pricing**. A result event is one item saved to the default dataset.

| Charge | Free plan | Bronze-Diamond plans |
| --- | ---: | ---: |
| Actor start | $0.01 | $0.01 |
| Result saved to the default dataset | $0.0025 per result | $0.00025 per result |

The Actor start event is charged according to memory, at one event per GB with at least one event per run. For example, 1,000 results cost about **$2.51 on the Free plan** or **$0.26 on a paid tier**, including one default Actor start.

Apify requires a maximum-charge limit of at least **$0.10 per run**. This limit caps potential spending; it is not a minimum fee. Available Apify credits can be applied to actual charges. Check the Actor's [current Pricing tab](https://apify.com/api-ninja/youtube-search-scraper/pricing) before a large run.

`maxResults` controls your upper bound. Avoid `scrapeAllResults` until you have tested a limited run, because broad queries can return a large dataset.

### Use YouTube Search Scraper through the API

Every run can be started programmatically with your Apify API token. This example runs the Actor synchronously and returns its dataset items:

```bash
curl "https://api.apify.com/v2/acts/api-ninja~youtube-search-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_API_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query":"cats","maxResults":20,"type":"video"}'
```

See the ready-made [Python, JavaScript, CLI, OpenAPI, HTTP, and MCP examples](https://apify.com/api-ninja/youtube-search-scraper/api). You can also schedule recurring searches in Apify Console and send completed datasets to Google Sheets, Make, Zapier, webhooks, or your own application.

### Popular use cases

- **Content research:** find high-performing videos and gaps around a topic.
- **Creator discovery:** identify relevant channels and Shorts creators for partnerships.
- **Trend monitoring:** schedule the same query and compare newly published results.
- **SEO and keyword research:** study titles, descriptions, publication dates, and engagement signals.
- **Competitive intelligence:** monitor how competitors and categories appear in YouTube search.
- **Dataset creation:** supply structured public YouTube metadata to dashboards, agents, or data pipelines.

### FAQ

#### Do I need a YouTube API key?

No. When you run the published Actor on Apify, you only need an Apify account. The service credentials are managed by the Actor.

#### Why did I receive fewer results than `maxResults`?

`maxResults` is a ceiling, not a guarantee. YouTube may have fewer matching results, and the Actor skips ads and non-result listing containers. Try a broader query or remove some filters.

#### Why are some output fields missing?

Fields vary by result type, detail depth, and what YouTube makes public for a particular item. Deeper detail modes can return more data, but no individual field is guaranteed for every result.

#### Can I scrape every result?

Enable `scrapeAllResults` to follow continuation tokens until none remain. YouTube decides what is available, and broad searches may run for a long time or produce many billable rows. Test with `maxResults` first.

#### Can I download results as CSV or Excel?

Yes. Open the run's **Dataset** tab and choose JSON, CSV, Excel, XML, or another supported export format. You can also retrieve the dataset through the Apify API.

#### Is it legal to scrape YouTube search results?

The Actor collects publicly available search metadata. Web-scraping laws and platform terms vary by country and use case. You are responsible for using the data lawfully, respecting applicable rights and YouTube's terms, and avoiding the collection or misuse of personal data.

#### Where can I get help or request a custom solution?

Open the Actor's [Issues tab](https://apify.com/api-ninja/youtube-search-scraper/issues) with the run ID, a sanitized input, and a description of the expected result. You can also use the Issues tab to discuss custom YouTube data requirements.

### More YouTube scraping tools

| Actor                                                                                | What it does                                                        |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [YouTube Video Downloader](https://apify.com/api-ninja/youtube-video-downloader)     | Downloads video or audio and returns direct media links.            |
| [YouTube Channel Scraper](https://apify.com/api-ninja/youtube-channel-scraper)       | Extracts channel videos, Shorts, playlists, livestreams, and posts. |
| [YouTube Comments Scraper](https://apify.com/api-ninja/youtube-comments-scraper)     | Collects comments and replies for audience and sentiment analysis.  |
| [YouTube Transcript Scraper](https://apify.com/api-ninja/youtube-transcript-scraper) | Converts video URLs or IDs into structured transcript data.         |

# Changelog

This Actor's version history is a separate document: https://apify.com/api-ninja/youtube-search-scraper/changelog.md

# Actor input Schema

## `query` (type: `string`):

The YouTube keywords to search for.

## `type` (type: `string`):

Filter by YouTube entity type. Video filter returns all video types including videos, movies, and shorts.

## `videoDepthDetails` (type: `string`):

Level of detail for video information retrieval. Deeper levels require more processing time:
• Basic: Search results with video ID, title, view count, thumbnail (fastest)
• Standard: Full video details with transcript, summary, key moments, channel info, engagement metrics (moderate)
• Detailed: Technical metadata including privacy settings, restrictions, captions availability, geographic availability (slower)
• Complete: All available data combining standard + detailed + additional metadata (slowest)

## `maxResults` (type: `integer`):

Total number of results to fetch (ignored if "Scrape all" is enabled).

## `scrapeAllResults` (type: `boolean`):

Keep paginating until the API stops returning a continuation token. The number of results can be very large.

## `sortBy` (type: `string`):

Sort order for the results. Relevance by default. Note: sorting is not available for Shorts.

## `duration` (type: `string`):

Filter by video length.

## `uploadDate` (type: `string`):

Restrict results to a recent time range.

## `geo` (type: `string`):

ISO 3166-2 country code (e.g., US, GB, IN).

## `lang` (type: `string`):

Language code (e.g., en, es, fr).

## `features` (type: `object`):

Toggle any YouTube feature filters. Selected values are sent to YouTube API as a comma-separated "features" query param (e.g. HD,subtitles). The parametrs are AND (Intersection of filters)

## `local` (type: `boolean`):

If true, request localized data.

## Actor input object example

```json
{
  "query": "Automation",
  "type": "video",
  "videoDepthDetails": "basic",
  "maxResults": 100,
  "scrapeAllResults": false,
  "sortBy": "relevance"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "Automation"
};

// Run the Actor and wait for it to finish
const run = await client.actor("api-ninja/youtube-search-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "query": "Automation" }

# Run the Actor and wait for it to finish
run = client.actor("api-ninja/youtube-search-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "Automation"
}' |
apify call api-ninja/youtube-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,api-ninja/youtube-search-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/nfyn3ecod9uCDaoVH/builds/PfQFXjbzE9gE4mdX3/openapi.json