# YouTube Search Scraper: Videos, Shorts, Channels & Playlists (`automatic/youtube-search-scraper`) Actor

Scrape YouTube search results for any keyword: rank, title, channel, views, upload age, length and badges for videos, Shorts, channels and playlists. Use YouTube's own filters (upload date, length, 4K, live, Creative Commons), sort by popularity, set the country. No login or API key.

- **URL**: https://apify.com/automatic/youtube-search-scraper.md
- **Developed by:** [Philip Kirkbride](https://apify.com/automatic) (community)
- **Categories:** Videos, SEO tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 search results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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: Videos, Shorts, Channels & Playlists

Type a keyword and get YouTube's search results as a clean spreadsheet: rank, title, channel, views, upload age, length, thumbnail and badges for every video, Short, channel or playlist YouTube shows. Use the same filters as YouTube's own search menu, and track where videos rank for the keywords you care about.

### What you get

- **One row per search result, in YouTube's order**: rank, result type, video / channel / playlist ID, link, title, channel name and ID, view count, upload age with an estimated date, duration, thumbnail, and the Shorts, live and badge markers (4K, CC, New...).
- **YouTube's own filters**: result type (videos, Shorts, channels, playlists or everything), upload date (today, this week, month or year), length (under 3, 3–20 or over 20 minutes), features (live now, 4K, 360°, VR180, Creative Commons) and relevance or popularity order.
- **Only recent videos**: `publishedAfter` keeps results published after a date such as `2026-10-01` or `7 days`.
- **Any market**: search as a viewer in another country and interface language, for example `GB` and `en`, or `DE` and `de`.
- **Paste searches the way you have them**: plain keywords, YouTube search-results links, or the `startUrls` list and the input keys you already use with other YouTube scrapers.
- No login, API key or quota. Export JSON, CSV or Excel, or connect through the API.

### Use cases

- **Keyword and rank tracking**: schedule a daily run and see which videos rank for your keywords, and where your own videos sit.
- **Content research**: find the most popular videos on a topic this month, with views and length, before you plan your own.
- **Competitor and trend monitoring**: new uploads on a keyword this week, across countries.
- **Lead and creator discovery**: channel results for a niche, with channel IDs ready for a channel or comments scraper.

### Also available

The YouTube suite: pick the job.

| Actor | Use when |
|---|---|
| **YouTube Search (this Actor)** | Ranked keyword results with YouTube's search filters |
| [YouTube Scraper](https://apify.com/automatic/youtube-scraper) | Videos, channels, search results and comments |
| [YouTube Transcripts](https://apify.com/automatic/youtube-transcripts-scraper) | Bulk transcripts as text, SRT or VTT |
| [YouTube Outlier Finder](https://apify.com/automatic/youtube-outlier-finder) | Breakout videos that beat their channel median |

### Input

The Console prefill collects the top 10 results for one keyword:

```json
{
  "searchTerms": ["python tutorial"],
  "maxResultsPerQuery": 10
}
```

The most popular long videos on two keywords from the last 30 days, as shown in the UK:

```json
{
  "searchTerms": ["home espresso", "budget headphones"],
  "maxResultsPerQuery": 50,
  "sort": "popularity",
  "duration": "long",
  "publishedAfter": "30 days",
  "country": "GB"
}
```

| Field | What it does |
| --- | --- |
| `searchTerms` | Keywords, one per line. A pasted `youtube.com/results?search_query=…` link runs as that search. |
| `startUrls` | Search-results links as plain strings or `{"url": "…"}` objects. |
| `maxResultsPerQuery` | Results per search (1–5,000). If left unset, uses 20. |
| `type` | `video` (default), `shorts`, `channel`, `playlist` or `all`. |
| `sort` | `relevance` (default) or `popularity`. |
| `uploadDate` | `today`, `week`, `month` or `year`. For videos, Shorts or all types. |
| `duration` | `short` (under 3 min), `medium` (3–20 min) or `long` (over 20 min). For videos or all types. |
| `features` | Any of `live`, `4k`, `360`, `vr180`, `creative_commons`; videos must have all of them. |
| `publishedAfter` | A date (`2026-10-01`) or a period (`7 days`, `6 months`). |
| `country`, `language` | Search market, for example `GB` and `en`. If left unset, uses `US` and `en`. |
| `maxItems` | Hard total across all searches (default 1,000). |
| `maxPages` | Result pages per search (default 50). |

Switching from another YouTube scraper? Your usual keys work: `searchQueries`, `keywords`, `query`, `maxResults`, `sortingOrder`, `dateFilter`, `lengthFilter`, `isLive` / `is4K` / `is360` / `isVR180` / `hasCC`, `oldestPostDate`, `searchSort`, `searchType`, `searchFeatures`, `regionCode`, `geo` and `lang`. Each translated key is listed in `OUTPUT.notices`; when the same setting is given twice, this Actor's own field wins.

### Output example

Captured from a public search on November 13, 2026:

```json
{
  "query": "python tutorial",
  "rank": 1,
  "type": "video",
  "videoId": "nKPbfIU442g",
  "channelId": "UCtoo4_P6ilCj7jwa4FmA5lQ",
  "playlistId": null,
  "url": "https://www.youtube.com/watch?v=nKPbfIU442g",
  "title": "PYTHON course from ZERO (Complete)",
  "channelName": "Soy Dalto",
  "viewCount": 6270466,
  "publishedText": "3 years ago",
  "publishedAtEstimate": "2023-11-14T00:34:07Z",
  "publishedAtIsEstimate": true,
  "duration": 29190,
  "durationText": "8:06:30",
  "thumbnailUrl": "https://i.ytimg.com/vi/nKPbfIU442g/hq720.jpg",
  "isShort": false,
  "isLive": false,
  "badges": [
    "4K",
    "CC"
  ],
  "scrapedAt": "2026-11-13T18:34:07Z"
}
```

### Run summary

`OUTPUT` reports each search with its delivered rows and pages, any errors, the stopping reason and, with `publishedAfter`, how many older results were skipped. A search that YouTube answers with "No results found" ends the run successfully with `OUTPUT.status: "no_results"`, and so does a run where every result was older than `publishedAfter`. Earlier rows stay available when a later page fails. A charge cap reports "allowed N of M requested rows". Results are saved throughout the run.

### Pricing

**$0.002 per result ($2.00 per 1,000) plus $0.005 per Actor start event.** The start event is charged per GB of memory, rounded up with a minimum of one event. The default 512 MB run is one start event. Only delivered dataset rows generate row events.

These examples use the default 512 MB memory:

| Example | Results | Cost |
| --- | ---: | ---: |
| Console prefill | 10 | $0.025 |
| 100 results | 100 | $0.205 |
| 1,000 results | 1,000 | $2.005 |

### Good to know

- Public, logged-out YouTube search only. Private, deleted, members-only and age-restricted results are not available.
- `publishedAfter` reads the age YouTube shows ("3 weeks ago"), so it is approximate: a video uploaded just before your date can be kept, and a newer one is never dropped. When `uploadDate` is empty, the smallest YouTube upload-date filter that covers your date is applied first. Shorts results show no upload age, so for Shorts the date comes from that YouTube filter alone; `OUTPUT.publishedAfter.undated` counts them. `publishedAfter` does not apply to channel or playlist results.
- Popularity is YouTube's own ranking, not a strict view-count sort. YouTube's search menu no longer offers date or rating order; those values from other scrapers are ignored with a notice. The HD, subtitles, 3D, HDR, location and purchased filters are not applied, because YouTube does not apply them reliably.
- View counts can be rounded as YouTube shows them. `publishedAtEstimate` is an estimate from the upload age (flagged by `publishedAtIsEstimate`); labels in languages other than English stay null. Fields missing from a result card are null.
- A video, channel or playlist link pasted as a search term is skipped with a note in `OUTPUT.errors` and is not charged. Filters inside a pasted search link are not used; set `type`, `uploadDate`, `duration`, `features` and `sort` instead.
- Duplicate results within one search are collapsed, including the watch and Shorts forms of the same video; the same video can appear under different searches. Pagination was verified through 19 pages and 300 results in one search; YouTube can end a search earlier.
- Country and language set the search market only; YouTube decides which results it shows there. Empty input (`{}`) runs a five-result example for "python tutorial" and says so in the run status.

# Actor input Schema

## `searchTerms` (type: `array`):

Words to search, one per line, for example python tutorial. A pasted YouTube search-results link also works. Empty input runs a five-result example.

## `startUrls` (type: `array`):

The common startUrls input format of other YouTube Actors: plain links or {"url": "…"} objects, for example \[{"url": "https://www.youtube.com/results?search_query=python+tutorial"}]. Each search-results link runs as that search. Combined with the search terms above, duplicates removed.

## `maxResultsPerQuery` (type: `integer`):

How many results to collect for each search, for example 50. If left unset, uses 20 (5 for the empty-input example).

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

Videos, Shorts, channels, playlists or every result type YouTube shows. If left unset, uses videos.

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

Relevance (YouTube's default order) or popularity. Popularity is YouTube's own ranking, not a strict view-count sort. If left unset, uses relevance.

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

Only videos uploaded in the last day, week, month or year, as in YouTube's filter menu. Empty applies no date filter. For videos, Shorts or all result types.

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

Only videos of this length. Empty applies no length filter. For videos or all result types.

## `features` (type: `array`):

Only videos with all the selected features, as in YouTube's filter menu. Empty applies no feature filter.

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

Only videos published on or after this date: 2026-10-01, or a relative value such as 7 days or 6 months. Read from the upload age YouTube shows ("3 weeks ago"), so it is approximate; a video just before the date can be kept, a newer one is never dropped.

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

Two-letter country code for the search market, for example GB or DE: the results YouTube shows in that country. If left unset, uses US.

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

YouTube interface language, for example en, es or de. If left unset, uses en. Titles are never translated.

## `maxItems` (type: `integer`):

Hard total across all searches, so you control the cost, for example 200. If left unset, uses 1000.

## `maxPages` (type: `integer`):

Safety limit for result pages per search, for example 10. If left unset, uses 50. YouTube can end a search sooner.

## `searchQueries` (type: `array`):

Same as Search terms; both lists are combined with duplicates removed, for example beginner guitar.

## Actor input object example

```json
{
  "searchTerms": [
    "python tutorial"
  ],
  "maxResultsPerQuery": 10,
  "maxItems": 1000,
  "maxPages": 50
}
```

# Actor output Schema

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

No description

## `summary` (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 = {
    "searchTerms": [
        "python tutorial"
    ],
    "maxResultsPerQuery": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automatic/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 = {
    "searchTerms": ["python tutorial"],
    "maxResultsPerQuery": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automatic/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 '{
  "searchTerms": [
    "python tutorial"
  ],
  "maxResultsPerQuery": 10
}' |
apify call automatic/youtube-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automatic/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/KvOyVbd2VCT88tujf/builds/bVcIfRbI6j1L6yXCN/openapi.json
