# YouTube Search Results & Entity Type Scraper (`vexaloom-labs/youtube-search-results-and-entity-type-scraper`) Actor

Search YouTube by keyword for videos, Shorts, channels, or playlists, with view counts, duration, and channel details, filterable by upload date, duration, sort order, and region.

- **URL**: https://apify.com/vexaloom-labs/youtube-search-results-and-entity-type-scraper.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Videos, Social media, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 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.
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 Results & Entity Type Scraper

Search YouTube without cookies or API keys and get structured rows for videos, Shorts, channels, playlists, and movies. Use YouTube's own filters, follow pagination, and optionally enrich every video with exact views and likes, dates when YouTube exposes them, and categories or tags when available.

### What this actor does

- **Five result types:** videos, Shorts, channels, playlists, and movies.
- **All-result mode:** mix the entity types in YouTube's own order.
- **Server-side filters:** upload date, duration, sort order, video features, market, and interface language.
- **Pagination:** follow continuation tokens until your limit or YouTube's own ceiling.
- **Optional details:** one detail request per video (plus fallback calls when needed) adds exact views and likes, dates when exposed, tags, and the full description.
- **Bulk queries:** run several searches in one job.
- **Cookieless:** public search data only. No login, no browser, no proxy setup.
- **Omit-empty output:** a row only contains values that are actually available.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `searchQueries` | array | — | One or more YouTube search terms. Duplicate terms are removed. |
| `maxResults` | integer | `20` | Results per query (1-1000). YouTube caps each entity type below 1000. |
| `scrapeAllResults` | boolean | `false` | Follow pages until YouTube stops returning results, ignoring `maxResults`. |
| `sortBy` | string | `relevance` | `relevance` or `view_count`. YouTube no longer supports date or rating sorting. |
| `uploadDate` | string | any | `last_hour`, `today`, `this_week`, `this_month`, or `this_year`. |
| `type` | string | all | `video`, `short`, `channel`, `playlist`, or `movie`. |
| `duration` | string | any | `short` (under 3 min), `medium` (3-20 min), or `long` (over 20 min). |
| `features` | array | `[]` | `hd`, `subtitles`, `creative_commons`, `live`, `4k`, `hdr`, `360`, `vr180`, `3d`. Multiple values are combined. |
| `market` | string | `US` | Country used for YouTube's search context. 31 markets are available. |
| `language` | string | `auto` | Interface language. `auto` follows the market. |
| `includeVideoDetails` | boolean | `false` | Fetch each video's detail payload for exact views, likes, and duration, plus dates, category, tags, and the full description when YouTube exposes them. |

#### Example: video search

```json
{
  "searchQueries": ["web scraping tutorial", "python automation"],
  "maxResults": 50,
  "type": "video",
  "sortBy": "view_count",
  "uploadDate": "this_year"
}
```

#### Example: Shorts

```json
{
  "searchQueries": ["lofi beats"],
  "type": "short",
  "maxResults": 100
}
```

#### Example: channels

```json
{
  "searchQueries": ["python tutorials"],
  "type": "channel",
  "market": "GB"
}
```

#### Example: exact video details

```json
{
  "searchQueries": ["apify"],
  "type": "video",
  "maxResults": 20,
  "includeVideoDetails": true
}
```

### Output

Every result row has `type`, `position` (1-based within the query), `searchQuery`, and `scrapedAt`. When YouTube exposes an estimate for the query, `estimatedResults` is added to each row.

#### Video and movie rows

| Field | Example |
|---|---|
| videoId | `"dQw4w9WgXcQ"` |
| title | `"Never Gonna Give You Up"` |
| url | `"https://www.youtube.com/watch?v=dQw4w9WgXcQ"` |
| description | result-card snippet |
| channelName | `"Rick Astley"` |
| channelId | `"UCuAXFkgsw1L7..."` |
| channelUrl | `"https://www.youtube.com/@RickAstley"` |
| channelHandle | `"@RickAstley"` when the byline links to a handle |
| channelVerified | `true` when the uploader has a verified badge |
| viewCount | exact integer when the card or details provide one |
| viewCountText | `"1.6B views"` or `"42,963 views"` (verbatim) |
| publishedTimeText | `"2 years ago"` |
| publishedAt | ISO 8601 UTC timestamp when a full time is exposed (`includeVideoDetails` only) |
| likeCount | exact integer (`includeVideoDetails` only) |
| category | `"Science & Technology"` when exposed (`includeVideoDetails` only) |
| tags | array of video keywords when exposed (`includeVideoDetails` only) |
| fullDescription | full description text (`includeVideoDetails` only) |
| duration | `"3:33"` |
| durationSeconds | `213` |
| thumbnails | array of `{url, width, height}` |
| richThumbnailUrl | animated preview URL when available |
| badges | result-card badges such as `["CC", "4K"]` |
| isLive | `true` for a live broadcast |
| isUpcoming | `true` for a scheduled premiere or live event |
| scheduledStartTime | ISO 8601 start time for upcoming videos (`includeVideoDetails` only) |
| concurrentViewers | current viewer count on a live card |

#### Channel rows

| Field | Example |
|---|---|
| channelId | `"UCxxxxxx"` |
| channelName | `"Python Programmer"` |
| channelUrl | `"https://www.youtube.com/@gilesmcmullen"` |
| handle | `"@gilesmcmullen"` |
| channelHandle | same handle, for consistency with video rows |
| description | search-card snippet |
| subscriberCount | approximate integer from YouTube's rounded label |
| subscriberCountText | `"782K subscribers"` |
| videoCount / videoCountText | only when YouTube shows a video count on the card |
| thumbnails | array of avatar images |
| isVerified | true or false |

#### Playlist and course rows

| Field | Example |
|---|---|
| playlistId | `"PLxxxxxxx"` |
| title | `"Python Full Course"` |
| url | `"https://www.youtube.com/playlist?list=PLxxxxxxx"` |
| channelName | `"CodeWithHarry"` |
| channelId | `"UCxxxxxx"` |
| channelUrl | `"https://www.youtube.com/@CodeWithHarry"` |
| channelHandle | `"@CodeWithHarry"` |
| videoCount / videoCountText | `100` / `"100 lessons"` when available |
| firstVideoId | first video shown on the card |
| thumbnails | array of playlist thumbnails |

#### Shorts rows

| Field | Example |
|---|---|
| videoId | `"abc123"` |
| title | `"A short example"` |
| url | `"https://www.youtube.com/shorts/abc123"` |
| viewCount | exact integer only when YouTube shows an unabridged count |
| viewCountText | `"1.2M views"` (verbatim) |
| thumbnails | vertical thumbnails |
| badge | card badge when present |
| isShort | `true` |

With `includeVideoDetails`, Shorts also gain `channelName`, `channelId`, `channelUrl`, `channelHandle`, `publishedAt`, `likeCount`, `durationSeconds`, `category`, and `tags`.

#### Status rows

A typed query with no results produces one status row: `recordType: "status"`, `status: "no_results"`, `query`, `market`, `resultType`, `appliedFilters`, and `resultCount: 0`. A failed query produces `status: "query_failed"` with an `error` string.

### How row limits work

YouTube serves a variable number of results for the same query. There is no fixed ceiling: the same `news` query returned 343-373 videos, 14-24 Shorts, 601-685 mixed rows, 134-367 channels, 357-461 playlists, and 204 movies on different runs and IPs. Set `scrapeAllResults` to follow pages until YouTube stops offering results, or use `maxResults` for a smaller slice. When the requested count is not reached, the status message reports the requested and actual counts and whether the query pool was exhausted, stopped after repeated empty pages, or lost its continuation. It does not claim a fixed ceiling.

### Limitations

- **Date and rating sorts are not available.** YouTube removed them; the UI suggests only relevance and view count. Saved tasks that still send `sortBy: "upload_date"` or `"rating"` are accepted and mapped to relevance with a warning.
- **Subscriber counts are rounded.** YouTube only publishes display labels for search results, so `subscriberCount` is an approximation and `subscriberCountText` is the verbatim label. Localized labels are parsed, including Japanese `チャンネル登録者数 184万人` and Korean `구독자 8.65만명`.
- **Some exact fields need a full player response.** On datacenter IPs YouTube can return a reduced response. Exact views, likes, and duration normally resolve, but `publishedAt` can be date-only or absent and `category`/`tags` can be omitted. The actor never fills these with zero or a placeholder.
- **Live view counts are a live counter.** For an active stream, the detail `viewCount` follows the current live counter and is not comparable to lifetime views. Use `concurrentViewers` on the card for the live audience.
- **Shorts can stop early.** Repeated empty continuation pages can end a Shorts run before the requested count. The run succeeds and the status message reports the requested and actual counts.
- **No comment counts.** Comments are handled by the dedicated YouTube comments actor.
- **Shorts cards are sparse.** Without `includeVideoDetails`, YouTube does not expose channel, date, duration, or exact views on a Shorts card.
- **Movies are YouTube's "Movies" filter.** It returns movie-catalog videos; some are full films, some are clips or episodes.
- **Results vary between runs.** YouTube personalizes and re-ranks search results over time.
- **Detail fields can be withheld.** On some datacenter IPs YouTube returns a limited player response. The actor tries a second player client and the watch-next payload; fields that remain unavailable (`viewCount`, `category`, `tags`, `publishedAt`) are omitted, never filled with zero or a placeholder.
- **Location and Purchased filters are not offered.** They return no cookieless results. Saved tasks that send `features: ["location"]`, `["purchased"]`, or `["cc"]` are accepted: `cc` maps to subtitles, the other two are ignored with a warning.

### FAQ

**Do I need cookies or a YouTube API key?**

No. The actor reads public search results with no credentials.

**Which result types can I request?**

Videos, Shorts, channels, playlists, and movies. Leave `type` empty for mixed results. Saved tasks that send the plural `shorts` are mapped to the Shorts type.

**Why did I get fewer rows than `maxResults`?**

YouTube serves a variable number of rows and there is no fixed ceiling. The status message reports the requested and actual counts and whether the query pool was exhausted or stopped after repeated empty pages. Some Shorts searches can stop early; the same shortfall message applies.

**What does `includeVideoDetails` add?**

Exact views, likes, and duration, plus publish date, category, tags, full description, and upcoming/live state when YouTube exposes them. It costs one or more requests per video and makes the run slower.

**Why is `viewCount` missing on some rows?**

YouTube shows rounded labels such as `1.6B views` on many cards. The actor keeps `viewCountText` but does not turn a rounded label into a fake exact number. Enable `includeVideoDetails` for exact views.

**Why is a channel's subscriber count approximate?**

Search cards only show rounded labels such as `782K subscribers`.

**Are Shorts supported without details?**

Yes. Title, URL, views text, and thumbnails are available. Channel, date, duration, and exact views require `includeVideoDetails`.

**Can I run several searches at once?**

Yes. Add them to `searchQueries`; each query gets its own `position` sequence and `searchQuery` value.

# Actor input Schema

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

One or more YouTube search terms. Each query is scraped separately and its results are combined in the dataset.

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

Maximum number of results per query. YouTube may serve fewer rows for a given query, entity type, session, or IP; the run reports the requested and actual counts and whether the result pool was exhausted.

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

Keep loading pages until YouTube stops offering results. This ignores Max Results Per Query and can take longer on broad searches.

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

Order of the search results. YouTube currently supports relevance and popularity (view count). Legacy values upload_date and rating are accepted for saved tasks and mapped to relevance with a warning.

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

Only return results uploaded in the selected period. Applies to videos and Shorts.

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

Restrict results to one entity type. Legacy plural value shorts is accepted and mapped to Shorts.

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

Filter videos by length. Applies to video and Shorts searches.

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

Filter videos by features. Multiple selections are combined. Legacy aliases cc, location, and purchased are accepted for saved tasks; cc maps to subtitles and the other two are ignored with a warning.

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

Country used for YouTube's search context (gl). Results and labels follow this market.

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

Language for YouTube labels and search text (hl). Auto follows the selected market.

## `includeVideoDetails` (type: `boolean`):

Fetch each video's public detail payload to add exact publish date, views, likes, category, tags, and full description. Adds one request per video and makes runs slower.

## Actor input object example

```json
{
  "searchQueries": [
    "apify"
  ],
  "maxResults": 3,
  "scrapeAllResults": false,
  "sortBy": "relevance",
  "uploadDate": "",
  "type": "video",
  "duration": "",
  "features": [],
  "market": "US",
  "language": "auto",
  "includeVideoDetails": false
}
```

# Actor output Schema

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

Dataset containing all scraped YouTube search result rows.

# 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 = {
    "searchQueries": [
        "apify"
    ],
    "maxResults": 3,
    "scrapeAllResults": false,
    "sortBy": "relevance",
    "uploadDate": "",
    "type": "video",
    "duration": "",
    "features": [],
    "market": "US",
    "language": "auto",
    "includeVideoDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/youtube-search-results-and-entity-type-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 = {
    "searchQueries": ["apify"],
    "maxResults": 3,
    "scrapeAllResults": False,
    "sortBy": "relevance",
    "uploadDate": "",
    "type": "video",
    "duration": "",
    "features": [],
    "market": "US",
    "language": "auto",
    "includeVideoDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/youtube-search-results-and-entity-type-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 '{
  "searchQueries": [
    "apify"
  ],
  "maxResults": 3,
  "scrapeAllResults": false,
  "sortBy": "relevance",
  "uploadDate": "",
  "type": "video",
  "duration": "",
  "features": [],
  "market": "US",
  "language": "auto",
  "includeVideoDetails": false
}' |
apify call vexaloom-labs/youtube-search-results-and-entity-type-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/youtube-search-results-and-entity-type-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/q1TdCUHc87k8c3NFU/builds/dDxnim0EkVlo74Ldw/openapi.json