# YouTube Related Videos Scraper – Recommendations (`scrapingmonkey/youtube-related-videos-scraper`) Actor

Collect public YouTube video recommendations from source URLs. Export related videos and Shorts, titles, channels, view labels, thumbnails, and source context with pagination.

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

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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?

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

Collect the video recommendations YouTube exposes beside a known video. **YouTube Related Videos Scraper** returns related video and Shorts cards with titles, channel details, view labels, thumbnails, and the source video attached to each result.

Use it to explore adjacent topics, compare recommendations across selected videos, or assemble candidate links for deeper review. Each source video has its own page budget and result sequence.

| At a glance | Details |
|---|---|
| 📥 Input | Full YouTube source-video URLs |
| 📤 Output | Video and Shorts cards with source-video context |
| 🔐 Login required | No YouTube credentials or cookies |
| ⚡ Processing | Up to 5 requests concurrently with automatic retries |
| 💾 Delivery | One row per collected result, with an input-specific position |

### What the YouTube related videos scraper extracts 🔎

The Actor collects public recommendation cards for the requested source video. It excludes the source video itself from the returned related items.

- Related video or Short ID, URL, type, title, and available description
- Thumbnail variants, duration, view count and original view text
- Publication text, badges, and visible live or upcoming indicators
- Channel identity, handle, avatar references, and verification
- Source video ID, title, URL, author, channel ID, and available views
- Sequential position within the collected results for that input

### How to scrape YouTube related videos 🚀

1. Add full source-video URLs to `inputList`.
2. Set `pagesPerInput` for each source video.
3. Run the Actor and compare recommendation rows by input and position.
4. Export related URLs or pass selected ones to Video Details Scraper.

```json
{
  "inputList": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "pagesPerInput": 2
}
```

### YouTube related videos data fields and output 📦

| Field group | Included data |
|---|---|
| Result | ID, URL, type, title, description, and position |
| Video card | Duration, views, source labels, publication text, and badges |
| Media and author | Thumbnail variants, channel identity, avatars, and verification |
| Source video | ID, URL, title, author, channel ID, and available views |

Complete illustrative success item. The content and values below are fictional examples, not a live result:

```json
{
  "input": "https://www.youtube.com/watch?v=TrailWalk01x",
  "status": "success",
  "id": "ForestLoop1",
  "url": "https://www.youtube.com/watch?v=ForestLoop1",
  "type": "video",
  "title": "Planning a forest day hike",
  "description": "A practical route guide with water stops and a packing checklist.",
  "thumbnail_url": "https://example.com/forest-loop.jpg",
  "thumbnails.url": [
    "https://example.com/forest-loop-small.jpg",
    "https://example.com/forest-loop.jpg"
  ],
  "thumbnails.width": [
    640,
    1280
  ],
  "thumbnails.height": [
    360,
    720
  ],
  "duration_seconds": 250,
  "duration_text": "4:10",
  "views": 8200,
  "views_text": "8.2K views",
  "published_text": "3 days ago",
  "badges": [],
  "is_live": false,
  "is_upcoming": false,
  "is_premiere": false,
  "is_members_only": false,
  "stream_status": null,
  "scheduled_start_time": null,
  "accessibility_text": null,
  "author.id": "UCaaaaaaaaaaaaaaaaaaaaaa",
  "author.name": "Trail Journal",
  "author.handle": "@trailjournal",
  "author.url": "https://www.youtube.com/@trailjournal",
  "author.avatar_url": "https://example.com/trail-avatar.jpg",
  "author.avatar_thumbnails.url": [
    "https://example.com/trail-avatar-small.jpg",
    "https://example.com/trail-avatar.jpg"
  ],
  "author.avatar_thumbnails.width": [
    80,
    160
  ],
  "author.avatar_thumbnails.height": [
    80,
    160
  ],
  "author.is_verified": false,
  "source_video.id": "TrailWalk01x",
  "source_video.url": "https://www.youtube.com/watch?v=TrailWalk01x",
  "source_video.title": "A forest walk in three stops",
  "source_video.channel_id": "UCaaaaaaaaaaaaaaaaaaaaaa",
  "source_video.author": "Trail Journal",
  "source_video.views": 12400,
  "position": 1
}
```

A related video occupies one row. `source_video.id` and the other source fields identify the video whose recommendations were collected. Thumbnail and avatar columns contain aligned lists; the same position within a group describes one image variant.

Missing optional fields can be `null`, empty strings, or empty lists. Some flags default to `false` when no signal is present. A failed row retains `input`, sets `status` to `failed`, and leaves the result-data fields null.

### Input requirements and coverage ⚙️

| Parameter | Type | Default | Rules |
|---|---|---|---|
| `inputList` | array of strings | Required | At least one full supported YouTube video URL; bare IDs are not accepted. |
| `pagesPerInput` | integer | `1` | Minimum 1, with no fixed upper limit. Limits result pages for each input; YouTube controls page size. |

Supported inputs include full watch URLs, youtu.be links, and supported /shorts/, /live/, /embed/, or /v/ links. The URL must identify an 11-character video ID; channel URLs and bare IDs are not accepted.

The collection covers the recommendations returned for the source video, without following each recommendation recursively. It does not reproduce a particular signed-in viewer's recommendation history.

Each input has its own collection order and duplicate tracking. Repeated results within that input are skipped; the same result may appear again under another input. Repeated input entries are processed separately.

The initial result page counts as page 1; each continuation uses another page. Collection ends at the budget or when YouTube stops providing a usable next page. If collection ends without any results, the Actor saves a failed row for that input. An empty end after saved results does not add a failure.

### YouTube recommendation use cases 🎯

#### Adjacent-topic research

Review titles and channels suggested beside selected source videos to identify nearby themes for further investigation.

#### Recommendation comparisons

Compare the returned cards for different source videos while retaining the source context on every row.

#### Candidate video discovery

Gather related links, select relevant candidates, and enrich them with full public video metadata.

#### Content-network snapshots

Save dated collections for your own analysis of how public recommendations change over repeated runs.

### Pricing and billable result rows 💰

Check the Actor's **Pricing** tab for the current charging model and rate.

Under dataset-item pricing, each saved success or failed row can be billable. Automatic retries do not independently create extra rows. Repeated input entries can produce repeated billable results.

The page budget is not an exact item count. Each collected result is a row; media variants and source context stay inside it. Repeated results under different inputs can create separate rows.

### YouTube Related Videos Scraper API and integrations 🔌

Use the Actor ID from the **API** tab as `$ACTOR_ID` and your Apify token as `$APIFY_TOKEN`.

```bash
curl -X POST "https://api.apify.com/v2/acts/$ACTOR_ID/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputList":["https://www.youtube.com/watch?v=jNQXAC9IVRw"],"pagesPerInput":2}'
```

This request starts a run. Retrieve the default dataset after completion, or use schedules and webhooks to connect it to a recurring workflow. Export JSON, CSV, or Excel, or send selected fields to Google Sheets, Make, Zapier, or your own application.

### Reliability and limits ⚠️

Temporary request failures are retried. Invalid or unavailable targets produce failed rows while other inputs can continue. A later-page failure can add a failed row alongside results already saved for the same input.

Recommendations can vary by region, time, availability, and the public response YouTube returns. The Actor does not guarantee the same sidebar a signed-in viewer sees. Missing recommendation containers or unavailable source videos can fail.

Card descriptions and counts may be partial. Numeric counts parsed from labels such as 8.2K are approximate; preserve `views_text` or other source labels where available. Use a details Actor when you need full descriptions or additional metadata.

### Frequently asked questions ❓

#### Does it return the source video too?

No. The source ID is excluded from the related result list and retained as context on the rows.

#### Are Shorts included?

Yes, when Shorts cards appear among the available recommendations.

#### Does it follow recommendations recursively?

No. It collects recommendation pages for the input videos, without opening each result's recommendations.

#### Will these match my account's recommendations?

Not necessarily. The Actor collects public responses without your signed-in account or viewing history.

#### Does two pages mean a fixed number of videos?

No. YouTube controls page size, and duplicate or unavailable cards can reduce the result count.

### Support, responsible use, and related actors 🛟

For a reproducible issue, share the run ID, a safe public input, and the field or behavior you expected through the Actor's support channel. Keep tokens and other credentials out of support messages.

Use public content in accordance with applicable privacy, copyright, contractual, and platform requirements.

# Actor input Schema

## `inputList` (type: `array`):

Add full YouTube video URLs, one per item. Raw video IDs are not accepted.

## `pagesPerInput` (type: `integer`):

Number of result pages to collect for each input. YouTube controls the page size. Results are saved after each page; collection stops when the list ends. Bootstrap requests do not count as result pages.

## Actor input object example

```json
{
  "inputList": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "pagesPerInput": 1
}
```

# Actor output Schema

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

Success and failed rows. Check the status column.

# 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 = {
    "inputList": [
        "https://www.youtube.com/watch?v=jNQXAC9IVRw"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapingmonkey/youtube-related-videos-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 = { "inputList": ["https://www.youtube.com/watch?v=jNQXAC9IVRw"] }

# Run the Actor and wait for it to finish
run = client.actor("scrapingmonkey/youtube-related-videos-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 '{
  "inputList": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ]
}' |
apify call scrapingmonkey/youtube-related-videos-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapingmonkey/youtube-related-videos-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/wKe85RBdLVFqSKNZG/builds/cdIbqCXQLW2mJXAqb/openapi.json