# YouTube Thumbnails · Views, Titles & Maxres (`corent1robert/youtube-thumbnail-scraper`) Actor

Scrape YouTube thumbnails with the metadata a designer actually uses: maxres image, title, views, and performance vs the set. Search a niche or paste competitor channels. One row per video.

- **URL**: https://apify.com/corent1robert/youtube-thumbnail-scraper.md
- **Developed by:** [Corentin Robert](https://apify.com/corent1robert) (community)
- **Categories:** Videos, Social media, Marketing
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.10 / 1,000 thumbnails

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

### What does YouTube Thumbnail Scraper do?

This Actor builds a **YouTube thumbnail brief** from [YouTube](https://www.youtube.com): the **image**, the **title**, **views**, which ones **outperform the rest**, and the **look** of the creative (vivid / dark / bright, text-heavy or not).

One row per video. Search a niche, paste competitor channels, or both. No Google key.

It is **not** a zip of random JPGs. It is **not** a video downloader. Generic YouTube scrapers give you a thumbnail URL. This one **opens the file**, drops blank maxres placeholders, and tags the look — so you can group a board the way a designer actually briefs.

![Thumbnails — Brief](docs/brief.png)

### Why scrape YouTube thumbnails?

You already know the job: a client wants a thumb that **gets the click**. Guessing from memory is slow. A folder of files with no views is worse.

This is for **thumbnail agencies**, **creative studios**, **MCNs**, and **YouTubers who A/B creatives**.

- Moodboard a niche (`personal finance`, `day in the life`, MrBeast-style faces)
- Audit a competitor’s last uploads before a pitch
- Sort by **what actually got views**, not by upload date
- Group by **look** (vivid vs dark vs bright) and **text on the thumb**
- Open **Thumbnails — Brief** in Console and **see the image** next to the numbers
- Export **CSV / Excel / JSON** and refresh on a schedule

On Apify you can **schedule** a weekly board and call it from the **API**.

### What data can this YouTube thumbnail scraper extract?

| You get | Why it matters on a brief |
|---|---|
| Thumbnail image | The real file. If maxres is a blank placeholder, you get HQ instead. |
| Title | The copy sitting on the thumb |
| Views | How hard that creative worked |
| Performance | 1 = typical for **this** board, 3 = three times the rest |
| Look | vivid / dark / bright / muted — from the pixels |
| Text on thumb | Big title-card energy, or a clean face / object |
| Channel + video link | Who to credit, what to click |

YouTube does **not** publish CTR. We do not invent it. No comments, no transcripts, no video files, no private videos.

### How to scrape YouTube thumbnails

1. Open this Actor in Apify Console.
2. Leave the keyword on **personal finance**, or type the niche you design for.
3. Optional: paste competitor channel links or `@handles`.
4. Leave **Long-form**, **Performance**, **50 videos**.
5. Run. Open **Thumbnails — Brief** — image, title, views, in one table.

Need a whole channel, not a 50-thumb board? Raise **Max videos**. A large creator catalog fits in one run.

See the **Input** tab for every option.

### How much does it cost?

You pay per **thumbnail in the dataset**, not per channel you scan. Actor start is **$0.00005**.

**Free plan:** 50 thumbs (one moodboard). Paid plans up to **10,000** (a full competitor audit).

| Apify plan | Per thumbnail | Per 1,000 |
|---|---|---|
| Free | **$0.003** | **$3.00** |
| Bronze | **$0.0027** | **$2.70** |
| Silver | **$0.0024** | **$2.40** |
| Gold | **$0.0021** | **$2.10** |
| Platinum | **$0.0018** | **$1.80** |
| Diamond | **$0.0015** | **$1.50** |

| Run | Approx. cost |
|---|---|
| One moodboard (50 thumbs) | **$0.15** |
| 200 thumbs | **$0.60** |
| 1,000 thumbs | **$3.00** |

Set a **max total charge** in Apify if you want a hard budget.

### Input

See the **Input** tab.

| Field | For the brief |
|---|---|
| Keyword | What’s working in the niche you pitch |
| Channels | What a competitor is shipping |
| Video links | You already have a list |
| Video type | Long-form by default (the landscape thumbs you sell). Shorts if that’s the brief. |
| Sort | Performance first. Views or newest if you prefer. |
| Min views / published | Drop noise and dead creatives |
| Max videos | 50 = one board. Higher = whole-channel audit |

### Output

Download **JSON, HTML, CSV, or Excel**.

```json
{
  "thumbnailUrl": "https://i.ytimg.com/vi/xxxxxxxxxxx/maxresdefault.jpg",
  "hasMaxres": true,
  "thumbMood": "vivid",
  "likelyHasText": true,
  "title": "I Tried Every Budget App",
  "viewsCount": 480000,
  "performanceIndex": 3.1,
  "channelTitle": "Example Finance",
  "videoUrl": "https://www.youtube.com/watch?v=xxxxxxxxxxx"
}
```

### Tips

- **Keyword** = the market. **Channel** = one competitor. Use both in the same run when you pitch.
- Performance is vs **this board**, not vs all of YouTube. Fifty finance thumbs compared to each other.
- View counts are what YouTube shows on the listing (often rounded). Good enough to rank a board, not for a finance report.

### FAQ

#### Is this a YouTube thumbnail downloader?

A downloader gives you files. This gives you a **brief**: image + title + views, sorted by what worked. If you only need a zip, a downloader is enough.

#### Do I need a YouTube API key?

No.

#### Can I pull a whole competitor channel?

Yes. Paste the channel, raise **Max videos**. Free plan stops at 50. Paid plans go up to 10,000.

#### Why isn’t there a CTR column?

YouTube does not make CTR public. Views and performance vs the board are what you can actually export.

#### How is this different from a YouTube video scraper?

Video scrapers dump catalogs and a thumbnail URL. This one is a **brief**: the image is in the table, maxres placeholders are skipped, Shorts stay off unless you want them, and each row has a **look** (vivid / dark / bright, text-heavy or not). You cannot get that from a URL alone.

#### Will Shorts pollute a landscape board?

No. Default is **long-form**. A 30-second clip is treated as a Short even if the link looks like a normal video.

### Is it legal to scrape YouTube thumbnails?

We only read **public** listings and images YouTube already shows. Use the export for legitimate creative research. Respect [YouTube’s terms](https://www.youtube.com/t/terms). Titles and faces can be personal data — you need a legitimate reason under GDPR.

### Related Actors

Need every upload with descriptions, not a thumbnail board? [YouTube Channel Videos](https://apify.com/corent1robert/youtube-channel-videos-scraper).

### Support

Issues tab on this Actor, or <corentin@outreacher.fr>. Automations: **API** tab.

# Actor input Schema

## `query` (type: `string`):

What you would type in YouTube Search. This is the **niche moodboard** — finance, MrBeast-style thumbnails, day in the life, etc. Combine with channels if you want both.

## `channelUrls` (type: `array`):

One per line: `https://www.youtube.com/@handle` or `@handle`. We go through their public videos until Max videos.

## `videoUrls` (type: `array`):

Optional. Watch or youtu.be links if you already have a list — you still get views and performance vs the rest of this board.

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

**Long-form (default):** skip Shorts. **Shorts:** only Shorts. **All:** both.

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

**Performance (default):** thumbs that beat the rest of this board, first. **Views:** raw count. **Newest:** last uploads (competitor audit).

## `minViews` (type: `integer`):

Skip noise. **0** = no floor. Try **1000** on a broad keyword.

## `publishedWithin` (type: `string`):

Drop old thumbs. Dates are what YouTube shows (“3 weeks ago”). **Any** keeps them all.

## `maxVideos` (type: `integer`):

How many thumbs in the board. **50** = one moodboard. Raise it to pull a whole competitor channel (up to **10,000** on paid plans). Free plan stops at **50**.

## Actor input object example

```json
{
  "query": "personal finance",
  "channelUrls": [],
  "videoUrls": [],
  "contentType": "videos",
  "sortBy": "performance",
  "minViews": 0,
  "publishedWithin": "any",
  "maxVideos": 50
}
```

# Actor output Schema

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

Image, title, views, performance

## `looks` (type: `string`):

Mood and text-on-thumb

## `assets` (type: `string`):

Maxres and HQ URLs

## `dataset` (type: `string`):

No description

## `output` (type: `string`):

No description

## `runLog` (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 = {
    "query": "personal finance",
    "channelUrls": [],
    "videoUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("corent1robert/youtube-thumbnail-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 = {
    "query": "personal finance",
    "channelUrls": [],
    "videoUrls": [],
}

# Run the Actor and wait for it to finish
run = client.actor("corent1robert/youtube-thumbnail-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 '{
  "query": "personal finance",
  "channelUrls": [],
  "videoUrls": []
}' |
apify call corent1robert/youtube-thumbnail-scraper --silent --output-dataset

```

## MCP server setup

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