# Youtube Scraper Api (`ilborso/youtube-scraper-api`) Actor

Extract FLAT JSON,CSV, Excel for search result pages: videos, channels, playlists, Shorts shelves, ads, discovery rails, and search refinement keywords.

- **URL**: https://apify.com/ilborso/youtube-scraper-api.md
- **Developed by:** [Fabio Borsotti](https://apify.com/ilborso) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.90 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Scraper API

An Apify Actor that searches YouTube and extracts structured JSON for search result pages: videos, channels, playlists, Shorts shelves, ads, discovery rails, and search refinement keywords.

***

### What does this Actor do?

This Actor executes YouTube searches and extracts comprehensive, **flat data** directly into the default Apify Dataset and Key-Value store. Usefull for cvs & excell extraction. **Always column are always present to facilitate cvs & excell extraction.**

- **Videos**: Video title, canonical watch URL, video ID, channel details (name, link, verified status, avatar thumbnail), published date, view counts (parsed integer and original string), duration length, description snippet, feature badges (`4K`, `LIVE`, `CC`, etc.), and thumbnails.
- **Channels**: Channel display name, link, handle (`@handle`), verified badge, subscriber count, description snippet, and avatar thumbnail.
- **Playlists**: Playlist title, link, channel information, video count, preview video links, and cover thumbnail.
- **Sponsored Ads**: Sponsored ad title, click-through URL, advertiser landing website, advertiser channel info (name and thumbnail), ad description text, static thumbnail, and position on page.
- **Shorts**: YouTube Short title, canonical link (`https://www.youtube.com/shorts/...`), video ID, view counts (parsed integer and localized text string), and shelf position on page.

***

### Key Features

- **Up to 30 Videos in One Request**: Set `num` (1–30) and the Actor pages internally until it collects the requested number of videos.
- **Result Type Filters**: Filter exclusively for videos, channels, or playlists via the `sp` parameter.
- **Flexible Sorting**: Sort results by relevance (default), rating, upload date (newest first), or view count.
- **Duration & Feature Filters**: Narrow results by duration (<4 min, 4–20 min, >20 min) or features (4K, HD, LIVE, closed captions).
- **Upload Date Filters**: Target videos uploaded in the last hour, today, this week, this month, or this year.
- **Localization**: Configure UI language (`hl`) to localize age and view-count strings, and country code (`gl`) to influence ranking and local shelves.
- **Device Emulation**: Switch between `desktop` and `mobile` search layouts.
- **Exact JSON Output**: Delivers clean, structured JSON directly into your Apify Dataset and Key-Value Store.

***

### Input Parameters

The Actor accepts the following input parameters:

#### Required

| Parameter | Type | Description |
|---|---|---|
| `search_query` | string | Search terms to look up on YouTube (e.g. `best laptop 2025`, `macbook pro m3`). *(Alias: `q`)* |

#### Optional

| Parameter | Type | Default | Description |
|---|---|---|---|
| `hl` | string | `"en"` | Interface language code (`en`, `de`, `fr`, `ja`, `tr`, `es`, `it`, …). Controls localized text such as `published_date`, `length`, and `views`. Choose from the dropdown list. |
| `gl` | string | `"us"` | Two-letter country code (`us`, `gb`, `de`, `fr`, `it`, `jp`, …). Influences search ranking and shelf availability. Choose from the dropdown list. |
| `device` | string | `"desktop"` | Device layout emulation: `desktop` or `mobile`. |
| `sp` | string | `""` | YouTube filter / sort option (e.g. `sort_by_view_count`, `type_channels`, `feature_4k`). Choose a predefined filter from the dropdown. **Cannot be combined with `num`.** |
| `num` | integer | — | Number of video results to return from a single request (`1`–`30`). When set, internal pagination retrieves up to `num` videos. **Cannot be combined with `sp`.** |

***

### Filter & Sort Options (`sp`)

The `sp` parameter controls sorting, filtering by result type, duration, features, and upload date using clean, human-readable option keys that are automatically mapped internally:

#### 1. Sort Order

| `sp` Option | Description |
|---|---|
| *(empty / omitted)* | Relevance (Default) |
| `sort_by_rating` | Sort by rating |
| `sort_by_upload_date` | Sort by upload date (newest first) |
| `sort_by_view_count` | Sort by view count |

#### 2. Result Type

| `sp` Option | Description | Output Populated |
|---|---|---|
| `type_videos` | Videos only | `video_results` |
| `type_channels` | Channels only | `channel_results` |
| `type_playlists` | Playlists only | `playlist_results` |

#### 3. Duration

| `sp` Option | Description |
|---|---|
| `duration_under_4_min` | Under 4 minutes (Short) |
| `duration_4_to_20_min` | 4–20 minutes (Medium) |
| `duration_over_20_min` | Over 20 minutes (Long) |

#### 4. Features

| `sp` Option | Description |
|---|---|
| `feature_4k` | 4K resolution |
| `feature_hd` | HD resolution |
| `feature_live` | Live streams currently active |
| `feature_subtitles` | Subtitles / Closed Captions (CC) |

#### 5. Upload Date

| `sp` Option | Description |
|---|---|
| `upload_last_hour` | Uploaded in the last hour |
| `upload_today` | Uploaded today |
| `upload_this_week` | Uploaded this week |
| `upload_this_month` | Uploaded this month |
| `upload_this_year` | Uploaded this year |

> \[!TIP]
> Raw YouTube continuation tokens or filter tokens passed directly to `sp` are also accepted and preserved.

***

### Result Count (`num`)

Setting `num` allows you to retrieve up to 30 videos in a single execution. The service pages internally until it collects `num` videos, deduplicates by `video_id`, and numbers `position_on_page` starting from 1.

> \[!NOTE]
>
> - `num` and `sp` are mutually exclusive. Provide either `num` or `sp`, not both.
> - When `num` is used, the response contains only `video_results` and discovery rails (`shorts_results`, `channel_results`, and `playlist_results` are omitted).
> - Recommendation shelves do not count toward `num`.

***

### Example Inputs

#### 1. Basic Search

```json
{
  "search_query": "best laptop 2025"
}
```

#### 2. Retrieve 25 Videos in a Single Run

```json
{
  "search_query": "best laptop 2025",
  "num": 25
}
```

#### 3. German Locale

```json
{
  "search_query": "beste laptop 2025",
  "hl": "de",
  "gl": "de"
}
```

#### 4. Channels Only

```json
{
  "search_query": "tech reviewer",
  "sp": "type_channels"
}
```

#### 5. Playlists Only

```json
{
  "search_query": "python tutorial for beginners",
  "sp": "type_playlists"
}
```

#### 6. 4K Videos Only

```json
{
  "search_query": "nature documentary 4k",
  "sp": "feature_4k"
}
```

#### 7. Long-Form Videos (> 20 Minutes)

```json
{
  "search_query": "podcast interview",
  "sp": "duration_over_20_min"
}
```

#### 8. Sort by View Count

```json
{
  "search_query": "best laptop 2025",
  "sp": "sort_by_view_count"
}
```

#### 9. Mobile Layout

```json
{
  "search_query": "workout routines",
  "device": "mobile"
}
```

***

### Output Structure

The Actor returns a **flattened list of JSON objects** directly pushed to the default Apify Dataset and Key-Value Store (`OUTPUT`). Each object represents an individual result item (`video_results`, `channel_results`, `playlist_results`, `ads_results`, or `shorts_results`).

Metadata wrappers (`search_parameters`, `search_information`, `pagination`) are excluded.

> \[!IMPORTANT]
> **Schema Consistency:** All 43 output parameters listed below will **always be present** in every single item of the returned dataset. If a parameter is not applicable to an item or not available, it will be empty (`""`). This ensures 100% predictable columns for tabular exports (CSV, Excel, databases).

#### All 43 Standardized Output Fields

Every returned object always contains these exact 43 keys:

| Field | Type | Description |
|---|---|---|
| `video_results.position_on_page` | integer / string | 1-based position of the video on the search results page |
| `video_results.title` | string | Video title |
| `video_results.link` | string | Canonical watch URL |
| `video_results.video_id` | string | YouTube video ID |
| `video_results.channel.name` | string | Channel display name |
| `video_results.channel.link` | string | Channel URL |
| `video_results.channel.thumbnail` | string | Channel avatar thumbnail URL |
| `video_results.published_date` | string | Relative published age localized to `hl` (e.g. `"6 mesi fa"`, `"4 months ago"`) |
| `video_results.views` | integer / string | View count parsed to integer |
| `video_results.length` | string | Video duration (e.g. `"21:02"`, `"12:38"`) |
| `video_results.description` | string | Video description snippet |
| `video_results.extensions.0` | string | Primary feature badge (e.g. `"4K"`, `"LIVE"`, `"Sottotitoli"`) |
| `video_results.thumbnail.static` | string | Static cover thumbnail URL |
| `video_results.thumbnail.rich` | string | Animated preview thumbnail URL |
| `channel_results.position_on_page` | integer / string | 1-based position of the channel on the search page |
| `channel_results.title` | string | Channel display name |
| `channel_results.link` | string | Channel URL |
| `channel_results.handle` | string | Channel `@handle` slug |
| `channel_results.subscribers` | integer / string | Subscriber count parsed to integer |
| `channel_results.description` | string | Channel description snippet |
| `channel_results.thumbnail` | string | Channel avatar thumbnail URL |
| `playlist_results.position_on_page` | integer / string | 1-based position of the playlist on the search page |
| `playlist_results.title` | string | Playlist title |
| `playlist_results.link` | string | Playlist URL |
| `playlist_results.channel.name` | string | Uploader channel display name |
| `playlist_results.channel.link` | string | Uploader channel URL |
| `playlist_results.videos.0.link` | string | Link to the first preview video in the playlist |
| `playlist_results.video_count` | integer / string | Total video count on the playlist badge |
| `playlist_results.thumbnail` | string | Playlist cover thumbnail URL |
| `ads_results.position_on_page` | integer / string | 1-based position of the sponsored ad on the search page |
| `ads_results.title` | string | Sponsored ad title |
| `ads_results.link` | string | Sponsored ad click-through URL |
| `ads_results.website` | string | Advertiser landing website URL |
| `ads_results.channel.name` | string | Advertiser name or domain |
| `ads_results.channel.thumbnail` | string | Advertiser icon / thumbnail URL |
| `ads_results.description` | string | Sponsored ad description text |
| `ads_results.thumbnail.static` | string | Static ad thumbnail image URL |
| `shorts_results.position_on_page` | integer / string | 1-based position of the Shorts shelf on the search page |
| `shorts_results.shorts.title` | string | Short video title |
| `shorts_results.shorts.link` | string | Short watch URL (`https://www.youtube.com/shorts/...`) |
| `shorts_results.shorts.views_original` | string | Localized view count text (e.g. `"1.2M views"`) |
| `shorts_results.shorts.views` | integer / string | Short view count parsed to integer |
| `shorts_results.shorts.video_id` | string | Short video ID |

***

#### Example Output Records

##### 1. Channel Result Example

When a channel is retrieved, channel fields are populated and other fields remain empty strings (`""`):

```json
{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": 25,
  "channel_results.title": "Top 5 Tech   ",
  "channel_results.link": "https://www.youtube.com/@Top5Tech_",
  "channel_results.handle": "@Top5Tech_",
  "channel_results.subscribers": 523,
  "channel_results.description": "Benvenuti nel nostro canale YouTube dedicato alle recensioni di prodotti! Esplora il mondo delle ultime novità, dai gadget ...",
  "channel_results.thumbnail": "https://yt3.ggpht.com/QMgqMPtfAEYmD4sSDHtw82CFK-HZ-U82q-CXVa7nPajohhJF0TAbeTn2uwm6UQnCtueXBZT-5iI=s88-c-k-c0x00ffffff-no-rj-mo",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}
```

##### 2. Video Result Example

When a video is retrieved, video fields are populated and other fields remain empty strings (`""`):

```json
{
  "video_results.position_on_page": 2,
  "video_results.title": "MIGLIORI NOTEBOOK di SETTEMBRE 2026 #TopBook",
  "video_results.link": "https://www.youtube.com/watch?v=eANiioMW39M",
  "video_results.video_id": "eANiioMW39M",
  "video_results.channel.name": "TuttoTech",
  "video_results.channel.link": "https://www.youtube.com/@TuttoTech",
  "video_results.channel.thumbnail": "https://yt3.ggpht.com/6IvsXMFmButt6XXcZUOu_3Uehk7AzEoze3oc984Re6nIGmFrS1CQqW_UiRGUyv4Tvf5tSnAYGw=s68-c-k-c0x00ffffff-no-rj",
  "video_results.published_date": "1 mese fa",
  "video_results.views": 28026,
  "video_results.length": "16:02",
  "video_results.description": "Questa non è una lista di tutti i portatili del 2026 ma una selezione accurata dei migliori notebook per rapporto qualità-prezzo.",
  "video_results.extensions.0": "4K",
  "video_results.thumbnail.static": "https://i.ytimg.com/vi/eANiioMW39M/hq720.jpg",
  "video_results.thumbnail.rich": "https://i.ytimg.com/an_webp/eANiioMW39M/mqdefault_6s.webp",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}
```

##### 3. Playlist Result Example

When a playlist is retrieved, playlist fields are populated and other fields remain empty strings (`""`):

```json
{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": 2,
  "playlist_results.title": "#TopBook",
  "playlist_results.link": "https://www.youtube.com/playlist?list=PLpBWoHEpd0ayObBsMGMh_yjfnvQ0ncx-x",
  "playlist_results.channel.name": "TuttoTech",
  "playlist_results.channel.link": "https://www.youtube.com/@TuttoTech",
  "playlist_results.videos.0.link": "https://www.youtube.com/watch?v=eANiioMW39M&list=PLpBWoHEpd0ayObBsMGMh_yjfnvQ0ncx-x",
  "playlist_results.video_count": 68,
  "playlist_results.thumbnail": "https://i.ytimg.com/vi/eANiioMW39M/hq720.jpg",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}
```

##### 4. Sponsored Ad Result Example

When an ad is retrieved, `ads_results` fields are populated and other fields remain empty strings (`""`):

```json
{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": 4,
  "ads_results.title": "See Top Picks of October 2026 - Best Laptops - Official Laptop Buying Guide",
  "ads_results.link": "https://www.google.com/aclk?sa=L&ai=DChs...",
  "ads_results.website": "https://www.google.com/aclk?sa=L&ai=DChs...",
  "ads_results.channel.name": "https://www.pcmag.com/top-10-picks/laptops",
  "ads_results.channel.thumbnail": "https://tpc.googlesyndication.com/simgad/12940295094016054608",
  "ads_results.description": "PCMag.Com Delivers Labs-Based, Independent Reviews Of The Latest Products. See Our #1 Pick. Lab Tested Reviews by...",
  "ads_results.thumbnail.static": "https://tpc.googlesyndication.com/simgad/12940295094016054608",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}
```

##### 5. YouTube Short Result Example

When a short is retrieved, `shorts_results` fields are populated and other fields remain empty strings (`""`):

```json
{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": 14,
  "shorts_results.shorts.title": "Top 10 BEST LAPTOP Brands 2025!",
  "shorts_results.shorts.link": "https://www.youtube.com/shorts/Wq6_eILGrpU",
  "shorts_results.shorts.views_original": "1.2M views",
  "shorts_results.shorts.views": 1200000,
  "shorts_results.shorts.video_id": "Wq6_eILGrpU"
}
```

***

### Error Handling

If an error occurs or invalid input parameters are provided, the Actor reports a descriptive status message and halts cleanly:

| Cause | Error Message / Status |
|---|---|
| Missing search terms | `Missing required input parameter 'search_query'.` |
| Invalid `device` | `Parameter 'device' must be one of: 'desktop', 'mobile'.` |
| Invalid `num` | `Parameter 'num' must be an integer between 1 and 30.` |
| Combined `sp` and `num` | `Parameters 'num' and 'sp' cannot be combined. Please provide either 'num' or 'sp', not both.` |
| Upstream service error | Descriptive error message with HTTP status code and details. |

***

### Related Actors & Recommended Workflow

Looking to extract full transcripts, subtitles, or AI summaries from the videos you found?

Check out **[Youtube Text, AI & Metadata Scraper](https://apify.com/ilborso/youtube-text-scraper)**:

- **Full Transcripts & Subtitles**: Extract complete, timestamped transcripts and subtitles in any available language.
- **AI Summarization**: Automatically generate AI-powered summaries, key topics, and takeaways from long videos.
- **Deep Metadata**: Retrieve detailed view counts, likes, hashtags, complete descriptions, and publication details.
- **Perfect Pipeline**: Combine this Actor (for search discovery and URL gathering) with **[Youtube Text, AI & Metadata Scraper](https://apify.com/ilborso/youtube-text-scraper)** for full video analysis and text extraction.

# Actor input Schema

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

Search terms to look up on YouTube (e.g. 'best laptop 2025', 'macbook pro m3'). Alias: q.

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

Interface language (e.g., 'en', 'de', 'fr', 'ja', 'tr', 'es', 'it'). Controls published_date, length, and views text.

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

Two-letter country code (e.g., 'us', 'gb', 'de', 'fr', 'it', 'jp'). Influences ranking and which shelves appear.

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

Device layout emulation: 'desktop' or 'mobile'. Mobile returns the mobile layout.

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

Filter or sort option for YouTube results (e.g., sort by view count, channels only, 4K, duration). Cannot be combined with 'num'.

## `num` (type: `integer`):

Number of video results to return from a single request (1–30). The service pages internally to retrieve up to this number of videos. Cannot be combined with 'sp'.

## Actor input object example

```json
{
  "search_query": "best laptop 2025",
  "hl": "en",
  "gl": "us",
  "device": "desktop",
  "sp": ""
}
```

# 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 = {
    "search_query": "best laptop 2025",
    "hl": "en",
    "gl": "us",
    "device": "desktop"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ilborso/youtube-scraper-api").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 = {
    "search_query": "best laptop 2025",
    "hl": "en",
    "gl": "us",
    "device": "desktop",
}

# Run the Actor and wait for it to finish
run = client.actor("ilborso/youtube-scraper-api").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 '{
  "search_query": "best laptop 2025",
  "hl": "en",
  "gl": "us",
  "device": "desktop"
}' |
apify call ilborso/youtube-scraper-api --silent --output-dataset

```

## MCP server setup

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

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/ab0iKbXtE1miVCfio/builds/B3MphjFgPDJgBEPZL/openapi.json