# YouTube Related Videos: the watch-next list for any video (`steadydata/youtube-related-videos`) Actor

The related videos YouTube shows next to a video, up to 100 videos per run: one row per suggestion with rank, title, channel, views, length and thumbnail, as an anonymous viewer in a chosen country sees them. Pay per related video.

- **URL**: https://apify.com/steadydata/youtube-related-videos.md
- **Developed by:** [Steadydata Team](https://apify.com/steadydata) (community)
- **Categories:** Videos, AI, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 related video listeds

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?

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 Related Videos: the watch-next list for any video

The related videos YouTube shows next to a video, up to 100 videos per run: one row per suggestion with rank, title, channel, views, length and thumbnail, as an anonymous viewer in a chosen country sees them. Pay per related video.

### Why this scraper

- **Only delivered results are charged.** Inputs that fail come back as clear error
  records at no cost.
- One light request per page of suggestions over YouTube's mobile route, no browser: the same list YouTube renders next to the video, read as data. Measured on two videos: 30 suggestions each, with title, channel, views, length and thumbnail, for less than a tenth of a cent per video.
- The list is what an anonymous viewer in the chosen `country` gets, so it is YouTube's generic association for that video, not a personal feed. Each row carries the channel id, so the suggestions can be grouped by channel; the source video is never repeated in its own list.

### Who this is for

Paste video URLs, youtu.be links or 11-character ids in `videos` (up to 100 per run), set `maxRelatedPerVideo` (default 20, ceiling 100) and optionally the `country` of the anonymous viewer. Every row carries the source video id, the rank, the suggested video's id, URL, title, channel name, channel id and URL, view count, length in seconds and thumbnail.

### Who this is not for

Suggestions are YouTube's and change between runs and countries; two runs an hour apart overlap heavily but are not identical. They are computed for an anonymous viewer, so they never reflect a specific account's history. View counts are YouTube's rounded figures (1.6M becomes 1600000); a live stream in the list has no view count. A video YouTube cannot show (private, deleted) comes back as one free `NO_RELATED` error row.

### Input example

```json
{
    "videos": [
        "https://www.youtube.com/watch?v=ifI_fwg55k8"
    ],
    "maxRelatedPerVideo": 20,
    "country": "US"
}
```

### Output example

- `sourceVideoId`
- `position`
- `videoId`
- `url`
- `title`
- `channelName`
- `channelId`
- `channelUrl`
- `viewCount`
- `durationSeconds`
- `thumbnailUrl`

Error codes: `INVALID_VIDEO_ID`, `VIDEO_UNAVAILABLE`, `NO_RELATED`, `BLOCKED`.

One delivered row looks like this:

```json
{
  "sourceVideoId": "ifI_fwg55k8",
  "position": 1,
  "videoId": "tEmLMCPK8OE",
  "url": "https://www.youtube.com/watch?v=tEmLMCPK8OE",
  "title": "Retro Tech: Teleportation",
  "channelName": "Marques Brownlee",
  "channelId": "UCBJycsmduvYEL83R_U4JriQ",
  "channelUrl": "https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ",
  "viewCount": 1600000,
  "durationSeconds": 1212,
  "thumbnailUrl": "https://i.ytimg.com/vi/tEmLMCPK8OE/hq720.jpg?sqp=-oaymwEhCK4FEIIDSFryq4qpAxMIARUAAAAAGAElAADIQj0AgKJD&rs=AOn4CLA3QaiwGm7fdmIm9d8v5m-qGKV_Ow",
  "status": "ok"
}
```

### Related actors from steadydata

- [youtube-video-details](https://apify.com/steadydata/youtube-video-details): full metadata of any of the related videos
- [youtube-search](https://apify.com/steadydata/youtube-search): search results for a keyword instead of a video
- [youtube-transcript-bulk](https://apify.com/steadydata/youtube-transcript-bulk): transcripts of the related videos

### Pricing

Pay per event: one `related-video-listed` event per delivered result. No charge for inputs
that fail, no separate platform-usage surcharge.

**Free Apify plan:** this actor delivers up to 25 rows per run for accounts on the Apify free
plan, and then stops with a message. That limit is set by us, not by Apify. It exists so the
actor keeps paying for itself for the people who do pay. Any paid Apify plan runs it at full
size, billed per delivered row, with failed rows never charged.

**Reviews:** if this actor saves you time, a short review on this page is the one thing that
helps most. Ratings are what other buyers look at first, and we have no other way to ask.

### FAQ

**Is this the same list as on youtube.com?** It is the list YouTube serves to a signed-out viewer in that country, in order; the website may add ads and personalised items on top.

**How deep can I go?** Up to 100 suggestions per video, paged like the website's endless list; `maxRelatedPerVideo` caps the cost.

**Do I pay for a video without suggestions?** No. Only delivered suggestion rows are charged.

**Can I get the full details of the suggested videos?** Pass the `videoId` column to the YouTube Video Details actor from the related actors below.

**Why does the channel id miss on a few rows?** Some cards (typically ads or mixes) carry no channel link; the name is still there.

**Is personal data collected?**
`position` is YouTube's order on the watch page, top to bottom.

**What happens when the source changes?**
Sources change from time to time; that is the nature of this work. The actor is
monitored daily and fixed fast, and while it is broken you are not charged, because
only delivered results cost anything.

# Changelog

This Actor's version history is a separate document: https://apify.com/steadydata/youtube-related-videos/changelog.md

# Actor input Schema

## `videos` (type: `array`):

One per row, up to 100: a video URL, youtu.be link or 11-character video id.

## `maxRelatedPerVideo` (type: `integer`):

Cost ceiling per video, in YouTube's order.

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

Two-letter country the anonymous viewer is placed in; suggestions differ per country.

## Actor input object example

```json
{
  "videos": [
    "https://www.youtube.com/watch?v=ifI_fwg55k8"
  ],
  "maxRelatedPerVideo": 20,
  "country": "US"
}
```

# Actor output Schema

## `results` (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 = {
    "videos": [
        "https://www.youtube.com/watch?v=ifI_fwg55k8"
    ]
};

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

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,steadydata/youtube-related-videos"
        }
    }
}
```

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/Ng2OtyhyiPbH8evxM/builds/criYpfeWs7OfhKX9l/openapi.json