# Youtube Video Scraper (`futurizerush/youtube-video-scraper`) Actor

Search YouTube and extract video metadata including titles, descriptions, view counts, channel info, and more. Filter by upload date, duration, and sort order.

- **URL**: https://apify.com/futurizerush/youtube-video-scraper.md
- **Developed by:** [Rush](https://apify.com/futurizerush) (community)
- **Categories:** Videos, AI, Agents
- **Features:** Limited permissions
- **Stats:** 59 total users, 1 monthly users, 96.7% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $10.00 / 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 Video Scraper

Find YouTube videos and Shorts by keyword, then export their descriptions, view counts, duration and channel information. Use the results for content research, topic discovery, competitor research or your own reporting workflows.

### Features

- Search YouTube with up to 50 keywords per run, in any language.
- Filter by upload date and duration, choose relevance or YouTube Popularity order, set a country preference, and include or leave out Shorts.
- Save one row per video with its title, link, thumbnail, channel, view count, expanded description and Short flag, plus duration and upload-time label for regular videos.
- Save each video once, even when several keywords find it.
- Check the Run Summary for every keyword's outcome, including videos left out because their details could not be verified.

### How to use

1. Open [YouTube Video Scraper](https://apify.com/futurizerush/youtube-video-scraper).
2. Enter your keywords, one per line, and choose how many videos to collect.
3. Adjust the optional filters and start the run.
4. Open **Output** to review videos and **Run Summary** to check whether any searches stopped early. Download results in a supported Apify export format, such as JSON, CSV or Excel.

### Input

| Input | Default | Meaning |
|---|---|---|
| `searches` | Required | 1–50 keywords, each up to 500 characters. Repeated keywords are collected once. Quotes, symbols and non-English text are preserved. |
| `maxResults` | `50` | Maximum unique videos across the run, from 1 to 500. |
| `maxPerSearch` | `20` | Maximum newly saved videos per keyword, from 1 to 100, bounded by the total maximum. |
| `uploadDate` | `any` | YouTube date filter: `any`, `today`, `week`, `month` or `year`. |
| `duration` | `any` | `short`: under 4 minutes; `medium`: 4–20 minutes inclusive; `long`: over 20 minutes. Videos with unknown duration, which includes every Short, are excluded when a duration filter is selected. |
| `sortBy` | `relevance` | `relevance` or `viewCount`. The latter selects **YouTube Popularity**, which can consider signals beyond views; it does not guarantee descending view counts. |
| `country` | `US` | A country preference from the Input form. This does not limit video language or channel location. |
| `includeShorts` | `true` | Include videos identified as Shorts in YouTube's search results. A short duration alone does not make a video a Short. |

Example input:

```json
{
  "searches": ["JavaScript tutorial", "React hooks"],
  "maxResults": 20,
  "maxPerSearch": 10,
  "uploadDate": "month",
  "duration": "medium",
  "sortBy": "relevance",
  "country": "US",
  "includeShorts": true
}
```

Limits are maximums, not guaranteed result counts. YouTube may provide fewer matching videos. Duplicate videos across keywords appear once and keep the keyword that first saved them. Results follow the order provided by YouTube; they are not a complete inventory of all matching videos.

### Output

One video per row, with these 14 fields:

| Field | Type | Meaning |
|---|---|---|
| `videoId` | string | Stable YouTube video identifier. |
| `title` | string | Title available at collection time. |
| `url` | string | Video or Shorts link. |
| `thumbnailUrl` | string | Source-provided thumbnail, or an empty string when unavailable. |
| `duration` | string or null | Duration displayed in YouTube search, in `M:SS` or `H:MM:SS`; null when unavailable, and always null for Shorts. |
| `durationSeconds` | integer or null | The corresponding duration in seconds. |
| `channelName` | string | Verified channel name on the video page. |
| `channelUrl` | string | Channel link using its stable identifier. |
| `viewCount` | integer or null | Complete view count displayed consistently on the video page; null when unavailable, only abbreviated, or when the two displayed counts disagree. |
| `uploadTime` | string | YouTube's relative published-time label, when available; otherwise an empty string, which is always the case for Shorts. |
| `description` | string | Expanded description text displayed on the video page. Link labels may be shortened by YouTube. An explicitly empty description stays empty. |
| `isShort` | boolean | Whether the search result identifies the video as a Short. |
| `searchKeyword` | string | Keyword that first saved the video. |
| `extractedAt` | string | Collection timestamp in ISO 8601 format. |

Illustrative output using synthetic identifiers and values:

```json
{
  "videoId": "Example0001",
  "title": "Example video",
  "url": "https://www.youtube.com/watch?v=Example0001",
  "thumbnailUrl": "",
  "duration": "5:30",
  "durationSeconds": 330,
  "channelName": "Example channel",
  "channelUrl": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx",
  "viewCount": null,
  "uploadTime": "2 days ago",
  "description": "Example description with preserved line breaks.\nSecond line.",
  "isShort": false,
  "searchKeyword": "example keyword",
  "extractedAt": "2026-10-02T00:00:00.000Z"
}
```

**Run Summary** includes `collectionStatus`, `stopReason`, the saved video count and the outcome of each keyword. A `complete` report means the requested limits or the available search results were reached. A `partial` report means one or more searches did not finish, ended before reaching a video limit (the keyword's or the run's) with results that could not be verified, or left out several results they would have received. When saved delivery cannot be verified, the reported total may be null and the run fails for review.

`unverifiedVideos` counts the search results that could not be verified and were not saved, among the results each keyword reached before its limit; each keyword's `unverified` shows how many of them it found. When a run stops while a keyword is being searched, that keyword's count covers the videos it left out before the stop. A null count means it is unknown, for example when the run was cut off while that keyword was being searched, or in a summary written by an earlier version.

| Reason | Meaning |
|---|---|
| `result_limit` | The keyword reached its video limit, or the run reached its total video limit while the keyword was being searched. |
| `source_exhausted` | YouTube showed no further results for the keyword. |
| `total_limit` | The run's total limit was reached before the keyword started. |
| `SOURCE_NO_PROGRESS` | New videos stopped coming in, or the search reached its page limit; results may be incomplete. |
| `UNVERIFIED_RESULTS` | Some results YouTube listed could not be verified and were left out. |
| `SOURCE_CONTRACT` | YouTube returned information that could not be verified, such as several unreadable standard results on one page; the run stopped for review. |
| `SOURCE_RESTRICTED` | YouTube limited access to the results. |
| `SOURCE_UNAVAILABLE` | YouTube did not respond as expected to a search page or to several video pages in a row; try again later. |
| `RESOURCE_LIMIT` | The run reached its collection limit. |
| `RESOURCE_SHARE` | The keyword stopped early so that the keywords after it could still be searched. |
| `PAYMENT_LIMIT` | The run reached its result allowance, such as the maximum charge set for the run. |
| `INTERRUPTED` | The run was stopped or moved before collection finished. |
| `PERSISTENCE_UNCERTAIN` | A saved delivery could not be confirmed; review the saved results. |
| `PRICING_UNVERIFIED` | The run's result allowance could not be checked, so no further videos were requested. |
| `INTERNAL_ERROR` | The run could not finish; contact support with the run link. |

### FAQ

**Why are there fewer videos than requested?**
Filters, duplicate results, source availability and the run's result allowance can reduce the total. A video whose page cannot be verified or does not load as expected is left out and the next one is tried; a keyword that leaves out several videos it would have received is marked incomplete. A keyword ends early when new videos stop coming in or its search reaches the page limit, or when going further would use the part of the run's allowance that the keywords after it need. The run stops when access is limited, or when YouTube does not respond as expected to a search page or to several video pages in a row. If several videos in a row, or several standard search results on one page, cannot be verified, the run stops and is marked as failed for review. Videos saved before any stop stay in the Dataset. Review Run Summary for the reason. Increasing a maximum does not guarantee more results.

**Can I search in Chinese or another language?**
Yes. Enter the words you want to search for and choose the country preference. Language and region can change which results YouTube provides. Results may differ from your signed-in or personalized search.

**Why are some titles or descriptions in English when the video is in another language?**
The Actor reads video details as YouTube displays them to English-language viewers. For videos in other languages, YouTube may show its own English translation of the title, description or channel name, so these fields can differ from the original text.

**Is the description a search snippet?**
No. Saved descriptions contain the expanded text displayed on the corresponding video page, including line breaks. YouTube may shorten link labels, so this is not a copy of the author’s original description with every full link restored. If the public description or video identity cannot be verified, that video is not saved as a verified result.

**Which channel is used for collaboration videos?**
The channel fields identify the publishing channel shown in the video’s details. Each row contains one channel.

**What happened to Last hour, Upload date order and Rating?**
Those input options are no longer supported. Requests using `uploadDate: "hour"` or `sortBy: "date"` / `"rating"` stop with a message asking you to select an available option. Update saved tasks to use the options shown in the Input form.

**Are views and other details fixed?**
No. They are snapshots and can change. Displayed duration can differ slightly from playback duration. A view count is saved only when the video's main and expanded details show the same complete number; abbreviated or unavailable counts remain null. Missing counts and durations are null, not zero. A missing upload-time label is not an inferred publication date.

**What happens if the run stops?**
Already saved videos remain in the Dataset. An interrupted search is not automatically collected again within the same run, to avoid duplicate results. Check its summary before deciding whether to start a new run. Starting a separate run creates a separate collection and can return videos you collected previously.

**Where can I check charges?**
Check the Actor’s Pricing tab for current result and platform usage charges before starting a run. The result limits control how many unique videos can be saved; they do not promise a fixed final bill.

**Does the Actor need my YouTube account?**
No account credentials are requested. Access is limited to information YouTube makes available without your account; private, removed, age-restricted or otherwise unavailable videos may not be collectable.

### Limitations and disclaimer

YouTube controls search availability, ranking, displayed metadata and access restrictions. The Actor cannot guarantee complete coverage, a fixed result count or access to every video. A country preference does not reproduce a specific person's search. Results can include text or links supplied by video publishers; review them before using or publishing them.

This Actor is independently developed and is not affiliated with or endorsed by YouTube or Google. Use collected information in accordance with applicable laws, platform terms and the rights of creators. Do not use it to obtain private information or bypass account restrictions.

Keywords: YouTube Video Scraper, YouTube search, video metadata, YouTube Shorts, video descriptions, content research, keyword research, Claude Code, OpenClaw, Gemini, Antigravity, Codex, ChatGPT

# Actor input Schema

## `searches` (type: `array`):

Enter 1–50 keywords, one per line. Duplicate keywords are collected once.

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

Total maximum number of videos to scrape across all keywords

## `maxPerSearch` (type: `integer`):

Maximum videos to scrape per search keyword

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

Filter videos by upload date

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

Keep any duration, under 4 minutes, 4–20 minutes inclusive, or over 20 minutes. Videos with unknown duration, which includes every Short, are omitted when a duration filter is selected.

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

Use YouTube’s relevance or popularity ranking. Popularity is not a strict sort by view count.

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

Country preference for search results. This does not restrict the channel’s country or the video language.

## `includeShorts` (type: `boolean`):

Include videos identified by YouTube as Shorts. Duration alone does not identify a Short.

## Actor input object example

```json
{
  "searches": [
    "AI automation"
  ],
  "maxResults": 20,
  "maxPerSearch": 10,
  "uploadDate": "any",
  "duration": "any",
  "sortBy": "relevance",
  "country": "US",
  "includeShorts": true
}
```

# Actor output Schema

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

No description

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

No description

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

No description

## `runSummary` (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 = {
    "searches": [
        "AI automation"
    ],
    "maxResults": 20,
    "maxPerSearch": 10,
    "uploadDate": "any",
    "duration": "any",
    "sortBy": "relevance",
    "country": "US",
    "includeShorts": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("futurizerush/youtube-video-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 = {
    "searches": ["AI automation"],
    "maxResults": 20,
    "maxPerSearch": 10,
    "uploadDate": "any",
    "duration": "any",
    "sortBy": "relevance",
    "country": "US",
    "includeShorts": True,
}

# Run the Actor and wait for it to finish
run = client.actor("futurizerush/youtube-video-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 '{
  "searches": [
    "AI automation"
  ],
  "maxResults": 20,
  "maxPerSearch": 10,
  "uploadDate": "any",
  "duration": "any",
  "sortBy": "relevance",
  "country": "US",
  "includeShorts": true
}' |
apify call futurizerush/youtube-video-scraper --silent --output-dataset

```

## MCP server setup

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