# Youtube Trending Scraper (`scraperforge/youtube-trending-scraper`) Actor

- **URL**: https://apify.com/scraperforge/youtube-trending-scraper.md
- **Developed by:** [ScraperForge](https://apify.com/scraperforge) (community)
- **Categories:** Automation, Lead generation, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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

## YouTube Trending Scraper

A powerful Apify Actor that scrapes YouTube trending videos from any country with support for multiple content types. This actor intelligently handles proxy management and data extraction to ensure reliable collection of comprehensive video metadata.

### Why Choose Us?

- **Smart Proxy Management**: Automatically uses proxies by default (YouTube often blocks Apify IPs) with intelligent fallback system
- **Multi-Country Support**: Scrape trending videos from 100+ countries worldwide
- **Content Type Filtering**: Filter by gaming, music, movies, sports, or entertainment
- **Flexible Video Limits**: Control how many videos to scrape per country (default: 10, set to 0 for unlimited)
- **Comprehensive Data Extraction**: Extracts complete video metadata including channel handles, thumbnails, and engagement metrics
- **Robust Error Handling**: Automatic retries, proxy fallback, and validation to ensure data quality
- **Production Ready**: Built with Apify SDK best practices for reliability and scalability

### Key Features

✅ **Intelligent Proxy System**
   - Uses proxy by default (recommended for YouTube scraping)
   - Automatically detects incomplete HTML responses
   - Falls back from datacenter → residential proxy if blocked
   - Retries up to 3 times with residential proxy
   - Sticks with working proxy for all remaining requests

✅ **Comprehensive Data Extraction**
   - Video title, description, and full metadata
   - View counts, likes, and comments
   - Channel information with handles (@username), subscriber counts, and badges
   - Thumbnails with dimensions
   - Categories, keywords, and tags
   - Publish dates, upload dates, and video duration
   - Live stream detection
   - Family-safe content flags

✅ **Flexible Input Options**
   - Country codes (BD, US, IN, etc.) — primary input; each row selects that region’s trending chart
   - YouTube URLs containing `gl=XX` to pick region `XX`

✅ **Multiple Content Types**
   - Gaming videos
   - Music content
   - Movies and entertainment
   - Sports highlights
   - General trending content

✅ **Video Limit Control**
   - Set maximum videos per input (default: 10)
   - Set to 0 for unlimited (scrape all available trending videos)
   - Perfect for sampling or comprehensive data collection

✅ **Data Quality Validation**
   - Validates extracted data before returning
   - Detects and retries on incomplete HTML responses
   - Ensures meaningful data (title, views, channel info)
   - Detailed logging for debugging

### Input

#### Input Schema

```json
{
  "startUrls": [
    "BD",
    "US",
    "IN"
  ],
  "contentType": "gaming",
  "maxVideosPerInput": 10,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
````

#### Input Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `startUrls` | Array | Yes | Two-letter ISO country codes (e.g. `BD`, `US`, `IN`) supported by the trending source—one per line. Unknown text falls back to `US`; a `youtube.com` URL with `gl=XX` uses region `XX`. |
| `contentType` | String | No | Type of content to scrape. Options: `music`, `gaming`, `movies`, `sports`, `entertainment`. Default: `gaming` |
| `maxVideosPerInput` | Integer | No | Maximum number of videos to scrape per input (country code). Set to `0` for unlimited (get all available trending videos). Default: `10` |
| `proxyConfiguration` | Object | No | Apify proxy configuration. Set `useApifyProxy: true` to use Apify Proxy (recommended when YouTube blocks). With `useApifyProxy: false`, the actor starts without proxy but may still enable proxy after blocks. |

#### Input Examples

**Example 1: Scrape 10 Gaming Videos from Bangladesh (Default)**

```json
{
  "startUrls": ["BD"],
  "contentType": "gaming",
  "maxVideosPerInput": 10
}
```

**Example 2: Scrape 50 Videos Per Country from Multiple Countries**

```json
{
  "startUrls": [
    "US",
    "GB",
    "CA"
  ],
  "contentType": "music",
  "maxVideosPerInput": 50
}
```

**Example 3: Get ALL Available Trending Videos (Unlimited)**

```json
{
  "startUrls": ["IN"],
  "contentType": "sports",
  "maxVideosPerInput": 0
}
```

**Example 4: Custom Proxy Configuration**

```json
{
  "startUrls": ["JP"],
  "contentType": "gaming",
  "maxVideosPerInput": 25,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

**Example 5: Disable Proxy (Not Recommended)**

```json
{
  "startUrls": ["US"],
  "contentType": "gaming",
  "maxVideosPerInput": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

### Output

#### Output Format

The actor outputs an array of video objects, each containing comprehensive video metadata:

```json
[
  {
    "type": "video",
    "id": "2dmCaK0qslM",
    "title": "Video Title Here",
    "status": "OK",
    "url": "https://www.youtube.com/watch?v=2dmCaK0qslM",
    "description": "Video description text...",
    "duration": 8940,
    "views": "1487513",
    "likes": "124690",
    "comments": "1K",
    "channel": {
      "id": "UCE-8FgcXvnAsb2EG1FizSyg",
      "name": "Channel Name",
      "handle": "@channelname",
      "url": "https://www.youtube.com/@channelname",
      "subscriberCount": "4.81M subscribers",
      "thumbnails": [],
      "badges": ["Verified"]
    },
    "keywords": [
      "keyword1",
      "keyword2",
      "keyword3"
    ],
    "isRatingsAllowed": true,
    "isLive": false,
    "isFamilySafe": true,
    "category": "Gaming",
    "isPrivate": false,
    "isExclusive": false,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/2dmCaK0qslM/maxresdefault.jpg",
        "width": 168,
        "height": 94
      }
    ],
    "embedUrl": "https://www.youtube.com/embed/2dmCaK0qslM",
    "isEmbeddable": true,
    "isUnlisted": false,
    "publishDate": "2025-10-31T07:06:17-07:00",
    "relativeDate": null,
    "uploadDate": "2025-10-31T07:06:17-07:00"
  }
]
```

#### Output Fields

| Field | Type | Description |
|-------|------|-------------|
| `type` | String | Always "video" |
| `id` | String | YouTube video ID |
| `title` | String | Video title |
| `status` | String | Status ("OK" or "UNKNOWN") |
| `url` | String | Full YouTube video URL |
| `description` | String | Video description |
| `duration` | Integer | Video duration in seconds |
| `views` | String | View count (formatted string) |
| `likes` | String | Like count (formatted string) |
| `comments` | String | Comment count (formatted string) |
| `channel` | Object | Channel information object |
| `channel.id` | String | Channel ID |
| `channel.name` | String | Channel name |
| `channel.handle` | String | Channel handle (e.g., "@channelname") or null |
| `channel.url` | String | Channel URL or null |
| `channel.subscriberCount` | String | Subscriber count (formatted string) |
| `channel.thumbnails` | Array | Channel thumbnails (currently empty) |
| `channel.badges` | Array | Channel badges (e.g., \["Verified"]) |
| `keywords` | Array | Video keywords/tags |
| `category` | String | Video category (Gaming, Music, etc.) |
| `thumbnails` | Array | Video thumbnail URLs with dimensions |
| `publishDate` | String | ISO 8601 publish date |
| `uploadDate` | String | ISO 8601 upload date |
| `isLive` | Boolean | Whether video is a live stream |
| `isFamilySafe` | Boolean | Family-friendly content flag |
| `isRatingsAllowed` | Boolean | Whether ratings are allowed |
| `isPrivate` | Boolean | Whether video is private (always false for trending) |
| `isExclusive` | Boolean | Whether video is exclusive |
| `isUnlisted` | Boolean | Whether video is unlisted |
| `isEmbeddable` | Boolean | Whether video can be embedded |
| `embedUrl` | String | Embed URL for the video |

### 🚀 How to Use the Actor (via Apify Console)

1. **Log in** at <https://console.apify.com> and navigate to **Actors**

2. **Find the actor** (youtube-trending-scraper) and click on it

3. **Configure inputs**:
   - Add country codes, URLs, usernames, or keywords in the `startUrls` field (one per line)
   - Select content type (gaming, music, movies, etc.)
   - Set `maxVideosPerInput` (default: 10, set to 0 for unlimited)
   - Optionally configure proxy settings (proxy is enabled by default)
   - Set sort order if needed

4. **Run the actor** by clicking the "Start" button

5. **Monitor logs** in real-time to see:
   - Progress updates every 10 videos
   - HTML extraction status (length, JSON structures detected)
   - Proxy switches and fallback events
   - Video processing status with extracted fields
   - Data validation warnings
   - Final statistics summary

6. **Access results** in the **OUTPUT** tab:
   - View data in the table format
   - Export to JSON or CSV
   - Download individual video data

7. **Export results**:
   - Click "Export" button
   - Choose format (JSON, CSV, Excel)
   - Download your data

### Best Use Cases

- **Content Research**: Discover trending topics and videos in specific regions
- **Market Analysis**: Track trending content across different countries and categories
- **Competitor Monitoring**: Monitor trending videos in your niche
- **Trend Discovery**: Find viral content and emerging trends
- **Data Collection**: Build datasets of trending videos for analysis
- **Content Strategy**: Understand what content performs well in different regions
- **SEO Research**: Identify trending keywords and topics
- **Social Media Marketing**: Find trending content to share or analyze
- **Influencer Research**: Discover trending channels and creators
- **Regional Content Analysis**: Compare trending content across countries

### How It Works

#### Proxy Management

The actor uses a smart proxy system:

1. **Default Behavior**: Proxy is enabled by default (recommended) because YouTube often blocks Apify IPs
2. **Detection**: Monitors HTML response quality (length, JSON structures)
3. **Validation**: Checks if extracted data is meaningful (title, views, channel info)
4. **Fallback**: If incomplete data detected, automatically tries proxy fallback
5. **Persistence**: Once a proxy works, uses it for all remaining requests

#### Data Extraction

The actor extracts data from multiple sources with priority:

1. **Basic HTML Extraction**: Meta tags, regex patterns (highest priority)
2. **Player Response**: YouTube's `ytInitialPlayerResponse` JSON
3. **Initial Data**: YouTube's `ytInitialData` JSON

Data is merged with priority: `basic > player > initial_data`, ensuring the most reliable data sources take precedence.

#### Quality Assurance

- Validates HTML contains expected YouTube JSON structures
- Checks for meaningful data (title, views, channel) before returning
- Retries with proxy if incomplete data detected
- Logs extraction quality for debugging

### Frequently Asked Questions

#### Why does the actor use proxy by default?

YouTube frequently blocks requests from Apify's IP addresses. Using a proxy by default ensures higher success rates and better data quality. You can disable it by setting `useApifyProxy: false` in proxy configuration.

#### How does the proxy fallback work?

The actor intelligently detects when YouTube returns incomplete HTML or blocks requests:

1. Monitors HTML response quality (length, JSON structures)
2. Validates extracted data completeness
3. If incomplete data detected, automatically falls back to datacenter proxy (SHADER)
4. If still blocked, switches to residential proxy (RESIDENTIAL)
5. Retries up to 3 times with residential proxy
6. Once a proxy works, uses that proxy for all remaining requests

#### What is `maxVideosPerInput`?

This parameter controls how many videos to scrape per country/input:

- **Default: 10** - Scrapes first 10 trending videos per country
- **Set to 0** - Scrapes ALL available trending videos (unlimited)
- **Any positive number** - Limits to that many videos per country

Example: If you set `maxVideosPerInput: 25` and provide 3 countries, you'll get up to 75 videos total (25 per country).

#### What countries are supported?

The actor supports 100+ countries including:

- United States (US)
- Bangladesh (BD)
- India (IN)
- United Kingdom (GB)
- Canada (CA)
- Japan (JP)
- Germany (DE)
- France (FR)
- Australia (AU)
- And many more...

Use the 2-letter ISO country code in the `startUrls` field.

#### Can I scrape specific channels or videos?

Currently, the actor focuses on trending videos. For specific channels or videos, you can:

- Use country codes to get trending videos from that region
- Filter by content type to narrow down results
- Future updates may include direct channel/video scraping

#### How many videos can I scrape?

The number of videos depends on:

- `maxVideosPerInput` setting (default: 10, set to 0 for unlimited)
- Number of countries/inputs provided
- Available trending videos for each country/content type
- Time of day (trending lists update frequently)

Example: With `maxVideosPerInput: 10` and 3 countries, you'll get up to 30 videos.

#### What happens if a request fails?

The actor includes robust error handling:

- Automatic retries (up to 3 attempts per video)
- Proxy fallback on blocks or incomplete data
- Data validation before returning results
- Graceful failure handling (continues with other videos)
- Detailed error logging with extraction status

#### Is the data real-time?

Yes! The actor scrapes current trending videos at the time of execution. YouTube's trending lists update frequently throughout the day.

#### Can I use my own proxies?

Yes! Configure custom proxies through the `proxyConfiguration` input field. The actor will use your proxy settings and still fallback if needed.

#### How long does scraping take?

Scraping time depends on:

- Number of videos to process
- `maxVideosPerInput` setting
- Network speed
- Proxy performance
- YouTube response times

Typically:

- 10 videos: 1-2 minutes
- 50 videos: 5-8 minutes
- 100 videos: 10-15 minutes

#### What if I get incomplete data?

The actor validates data quality:

- Checks for title, views, and channel information
- Detects incomplete HTML responses
- Automatically retries with proxy if needed
- Logs warnings for incomplete data
- Returns data even if incomplete after max retries (with warning)

Check the logs for extraction status and proxy fallback events.

### Support and Feedback

- **Issues**: Report bugs or request features through Apify platform
- **Questions**: Check the FAQ section above or contact support
- **Feedback**: We welcome suggestions for improvements

### Cautions

⚠️ **Important Legal and Ethical Considerations**

- **Public Data Only**: This actor collects only publicly available data from YouTube
- **Rate Limiting**: The actor includes delays and rate limiting to respect YouTube's servers
- **Terms of Service**: Ensure your use case complies with YouTube's Terms of Service
- **Data Privacy**: Be mindful of data privacy regulations (GDPR, CCPA, etc.) when processing personal information
- **Responsible Use**: Use the actor responsibly and avoid overwhelming YouTube's servers
- **No Private Content**: The actor cannot access private, unlisted, or password-protected content
- **Proxy Usage**: Using proxies may incur additional costs depending on your Apify plan

**Disclaimer**: The end user is responsible for ensuring legal compliance with all applicable laws, including but not limited to:

- Spam laws
- Privacy regulations
- Data protection laws
- YouTube Terms of Service
- Copyright laws

***

**Built with ❤️ using Apify SDK**

# Actor input Schema

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

✅ Put one 2-letter country code per line (US, GB, IN, BD, JP, …).

🗺️ Each line = that region’s trending chart. Unknown text → US; a youtube.com link with \&gl=XX uses region XX.

✨ Tip: mix regions to compare what’s hot worldwide.

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

🎵 Which vertical chart to read: music, gaming, movies, sports, or entertainment.

🎯 Default is gaming—switch to music or sports to match what you’re tracking.

## `maxVideosPerInput` (type: `integer`):

📹 Max trending videos to keep per country row (default 10).

♾️ Set 0 for unlimited (all IDs returned for that region’s page).

⚡ Lower = faster and lighter; higher = fuller sample.

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

🌍 Route traffic through Apify Proxy so YouTube is less likely to block or return thin pages.

🔄 Leave off for a direct run; if things get blocked, the actor can still step up through datacenter → residential automatically.

## Actor input object example

```json
{
  "startUrls": [
    "US"
  ],
  "contentType": "gaming",
  "maxVideosPerInput": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "startUrls": [
        "US"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scraperforge/youtube-trending-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 = {
    "startUrls": ["US"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scraperforge/youtube-trending-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    "US"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scraperforge/youtube-trending-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scraperforge/youtube-trending-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Youtube Trending Scraper",
        "version": "0.1",
        "x-build-id": "vzwxra3ZAobZerVqv"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/scraperforge~youtube-trending-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-scraperforge-youtube-trending-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/scraperforge~youtube-trending-scraper/runs": {
            "post": {
                "operationId": "runs-sync-scraperforge-youtube-trending-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/scraperforge~youtube-trending-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-scraperforge-youtube-trending-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "startUrls"
                ],
                "properties": {
                    "startUrls": {
                        "title": "🌍 Country codes (one per row)",
                        "type": "array",
                        "description": "✅ Put one 2-letter country code per line (US, GB, IN, BD, JP, …).\n\n🗺️ Each line = that region’s trending chart. Unknown text → US; a youtube.com link with &gl=XX uses region XX.\n\n✨ Tip: mix regions to compare what’s hot worldwide.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "contentType": {
                        "title": "🎮 Trending category",
                        "enum": [
                            "music",
                            "gaming",
                            "movies",
                            "sports",
                            "entertainment"
                        ],
                        "type": "string",
                        "description": "🎵 Which vertical chart to read: music, gaming, movies, sports, or entertainment.\n\n🎯 Default is gaming—switch to music or sports to match what you’re tracking.",
                        "default": "gaming"
                    },
                    "maxVideosPerInput": {
                        "title": "🔢 Videos per country row",
                        "minimum": 0,
                        "type": "integer",
                        "description": "📹 Max trending videos to keep per country row (default 10).\n\n♾️ Set 0 for unlimited (all IDs returned for that region’s page).\n\n⚡ Lower = faster and lighter; higher = fuller sample.",
                        "default": 10
                    },
                    "proxyConfiguration": {
                        "title": "🛡️ Proxies (recommended)",
                        "type": "object",
                        "description": "🌍 Route traffic through Apify Proxy so YouTube is less likely to block or return thin pages.\n\n🔄 Leave off for a direct run; if things get blocked, the actor can still step up through datacenter → residential automatically."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
