# Cheap Youtube Scraper (`apigeek/cheap-youtube-scraper`) Actor

The cheapest actor  to scrape YouTube videos, Shorts, live streams, channels, playlists, comments, replies, and subtitles. no API key required

- **URL**: https://apify.com/apigeek/cheap-youtube-scraper.md
- **Developed by:** [API Geek](https://apify.com/apigeek) (community)
- **Categories:** Videos, Social media, SEO tools
- **Stats:** 2 total users, 1 monthly users, 28.6% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.30 / 1,000 video 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Cheap YouTube Scraper

Scrape YouTube videos, Shorts, live streams, channels, playlists, comments, replies, and subtitles at a low cost. Cheap YouTube Scraper accepts URLs and search queries, uses lightweight YouTube web APIs, and requires no YouTube API key.

### Quick start

Provide `startUrls`, `searchQueries`, or both. Sources are additive and duplicate videos are emitted only once.

#### Scrape a video with comments

```json
{
  "startUrls": [{ "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw" }],
  "maxCommentsPerVideo": 20,
  "maxRepliesPerComment": 3,
  "commentSort": "TOP"
}
```

#### Search with filters

```json
{
  "searchQueries": ["apify tutorial", "web scraping"],
  "maxResultsPerSource": 50,
  "searchSort": "uploadDate",
  "searchUploadDate": "month",
  "searchHdOnly": true
}
```

`maxResultsPerSource` applies separately to each query, playlist, hashtag, or selected channel feed. A direct video URL always produces at most one video result.

#### Scrape channel videos, Shorts, and streams

```json
{
  "startUrls": [{ "url": "https://www.youtube.com/@Google" }],
  "channelContentTypes": ["videos", "shorts", "streams"],
  "maxResultsPerSource": 20
}
```

For a generic channel URL, every selected feed can produce up to the configured limit. A URL ending in `/shorts` or `/streams` targets only that feed.

#### Download subtitles

```json
{
  "startUrls": [{ "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw" }],
  "downloadSubtitles": true,
  "subtitleLanguage": "en",
  "subtitleFormat": "srt"
}
```

Subtitle content is stored in the run's default Key-Value Store. The video item contains `subtitle.storageKey`. If the requested language is unavailable, the video is still returned with its available `subtitleTracks` and an error record is written.

`searchHasSubtitles` only filters search results. It does not download subtitles; use `downloadSubtitles` for that.

### Input reference

| Input | Default | Purpose |
| --- | --- | --- |
| `startUrls` | `[]` | Video, Short, channel, playlist, search, or hashtag URLs |
| `searchQueries` | `[]` | YouTube search keywords or phrases |
| `maxResultsPerSource` | `20` | Result limit for each query, playlist, hashtag, or channel feed |
| `channelContentTypes` | `["videos"]` | Channel feeds: `videos`, `shorts`, and/or `streams` |
| `searchSort` | `relevance` | `relevance`, `uploadDate`, `viewCount`, or `rating` |
| `searchUploadDate` | — | `hour`, `today`, `week`, `month`, or `year` |
| `searchDuration` | — | `short`, `medium`, or `long` |
| `searchPublishedAfter` | — | Filter out videos older than an ISO date |
| `searchHdOnly`, `search4KOnly`, `searchLiveOnly` | `false` | Additional YouTube search filters |
| `searchHasSubtitles` | `false` | Search only for captioned videos |
| `maxCommentsPerVideo` | `0` | Top-level comments; `0` disables comments |
| `maxRepliesPerComment` | `0` | Replies collected for each emitted top-level comment |
| `commentSort` | `TOP` | `TOP` or `NEWEST` |
| `downloadSubtitles` | `false` | Download one matching caption track per video |
| `subtitleLanguage` | `en` | Caption language code, for example `en-US` or `id` |
| `subtitleFormat` | `text` | `text`, `json`, `srt`, or `vtt` |
| `proxyConfiguration` | — | Optional Apify Proxy configuration used by YouTube requests |

At least one non-empty URL or query is required. Invalid and retired fields fail before requests or charges with an actionable validation message.

### Output

The default dataset contains `VIDEO`, `SHORT`, `LIVE`, and `COMMENT` items. Comments and replies use the same `COMMENT` type and are distinguished by `isReply` and `parentCommentId`.

Each item includes `sourceInput`, identifying the URL or query that first produced it. Search results also include `searchQuery` and `searchPosition`; playlist results include playlist identity and position.

Additional output is available from the Actor run page:

- `CHANNEL_METADATA`: metadata for resolved channels.
- `PLAYLIST_METADATA`: metadata for resolved playlists.
- Subtitle files: records named `SUBTITLE_<videoId>_<language>_<format>`.
- `ERRORS` dataset: source-level and item-level failures that did not necessarily fail the whole run.

A run can succeed with partial errors when at least one source produced results. Validation errors and fatal failures are reported as failed Actor runs. A valid source with no matching results completes normally as `SOURCE_EXHAUSTED`.

### Billing

This Actor uses Apify pay-per-event billing. See the Actor's live **Pricing** tab for current unit prices; the store configuration is the source of truth.

- `apify-actor-start`: once per run, when configured by the platform.
- `video-result`: after a video, Short, or live-stream item is saved successfully.
- `comment-result`: after a comment or reply is saved successfully.
- `subtitle-result`: after a requested subtitle is downloaded and stored successfully.

No result event is charged before its corresponding output is persisted. The approximate run cost is the start event plus each successful event count multiplied by its live unit price.

### Local development

```bash
npm ci
npm run build
npm test
```

`npm run test:live` deliberately contacts live YouTube services. `npm run benchmark` runs the compiled benchmark suite after a build.

# Actor input Schema

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

Video, Short, channel, channel tab, playlist, search, or hashtag URLs.

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

Keywords or phrases to search. These are added to any URLs above.

## `maxResultsPerSource` (type: `integer`):

Maximum videos from each query, playlist, hashtag, or selected channel feed. Direct video URLs return one item.

## `channelContentTypes` (type: `array`):

Feeds collected from generic channel URLs. A URL ending in /shorts or /streams targets that feed directly.

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

Applied to queries and search URLs without their own YouTube filter parameters.

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

Only include search results uploaded within the selected period.

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

Only include search results in the selected duration range.

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

ISO date such as 2026-01-01. Older results are filtered out.

## `searchHdOnly` (type: `boolean`):

Only include search results available in HD.

## `search4KOnly` (type: `boolean`):

Only include search results available in 4K.

## `searchLiveOnly` (type: `boolean`):

Only include search results that are currently live.

## `searchHasSubtitles` (type: `boolean`):

Filters searches only. Enable subtitle downloading separately below.

## `maxCommentsPerVideo` (type: `integer`):

Top-level comments per video. Set to 0 to disable comment collection.

## `maxRepliesPerComment` (type: `integer`):

Requires maximum comments per video to be above 0.

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

Choose whether to collect top comments or newest comments first.

## `downloadSubtitles` (type: `boolean`):

Downloads one matching caption track per video to the Key-Value Store. This may create a subtitle billing event.

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

Language code such as en, en-US, es, or id.

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

File format used for downloaded subtitle content.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy settings used consistently for YouTube requests.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    },
    {
      "url": "https://www.youtube.com/@Google"
    }
  ],
  "searchQueries": [
    "bitcoin news",
    "apify tutorial"
  ],
  "maxResultsPerSource": 20,
  "channelContentTypes": [
    "videos"
  ],
  "searchSort": "relevance",
  "searchPublishedAfter": "2026-01-01",
  "searchHdOnly": false,
  "search4KOnly": false,
  "searchLiveOnly": false,
  "searchHasSubtitles": false,
  "maxCommentsPerVideo": 0,
  "maxRepliesPerComment": 0,
  "commentSort": "TOP",
  "downloadSubtitles": false,
  "subtitleLanguage": "en",
  "subtitleFormat": "text"
}
```

# Actor output Schema

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

Successful video, Short, live stream, comment, and reply records.

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

No description

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

No description

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

Named dataset reference for source-level and item-level failures.

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

Browse downloaded subtitle records and auxiliary output.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("apigeek/cheap-youtube-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("apigeek/cheap-youtube-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 '{}' |
apify call apigeek/cheap-youtube-scraper --silent --output-dataset

```

## MCP server setup

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