# YouTube Ad Scraper — Ads by Brand or Keyword (`scrapeio/youtube-ad-scraper`) Actor

Scrape YouTube ads by brand name, keyword, or brand ID. Video ID, title, thumbnail, spend estimates. Apify AI, MCP, and Cursor ready.

- **URL**: https://apify.com/scrapeio/youtube-ad-scraper.md
- **Developed by:** [Shop Intel](https://apify.com/scrapeio) (community)
- **Categories:** Social media, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## 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

## YouTube Ad Scraper — Brand & Keyword Transparency Ads | Shop Intel on Apify

**YouTube Ad Scraper** (Shop Intel / [ScrapeIO on Apify](https://apify.com/scrapeio)) collects **YouTube transparency-style ads** by **brand name**, **numeric brand ID**, or **free-text keyword**. Results land in a standard Apify **Dataset** (JSON, CSV, Excel, or XML) for market research, creative benchmarking, and paid-social intelligence.

### Use with Apify AI

[Apify AI](https://docs.apify.com/account/apify-ai) is live in Apify Console. Describe the job in plain English and it **finds this Actor, fills the input form, runs it, and returns the dataset**. The same ranking powers Store search and the [Apify MCP server](https://docs.apify.com/integrations/mcp) `search-actors` tool used by **Cursor**, Claude, ChatGPT, and other agents.

Use this Actor to scrape **YouTube ads** from Google's transparency-style ad index by brand or keyword. Open [YouTube Ad Scraper](https://apify.com/scrapeio/youtube-ad-scraper) or ask Apify AI with the prompts below.

#### Prompts that match this Actor

Type these in the **Apify Store search bar** (long, intent-heavy queries route to Apify AI) or the dashboard **Ask Apify AI** widget:

- "Get YouTube ads for Nike"
- "Scrape YouTube ad creatives by brand name"
- "Collect YouTube ads for a keyword like running shoes"
- "Pull YouTube transparency ads using a brand ID"
- "Export YouTube ad videos, titles, and spend estimates for a competitor"

#### How Apify AI fills the input

| You say | This Actor sets |
|---|---|
| brand or keyword | `query` |
| numeric brand ID from YouTube Brand Finder | `brandId` |
| how many ads (0 = no cap) | `maxResults` |

Apify AI always asks for confirmation before it runs. Nothing is charged until you approve.

#### Cursor, Claude, ChatGPT (Apify MCP)

Pin this Actor as a **default Cursor / MCP tool** so agents call `scrapeio/youtube-ad-scraper` instead of a random Store result. Keep `actors` + `docs` so Apify AI search still works, and list your suite so Cursor prefers these Actors.

**Cursor MCP URL (this Actor first):**

```text
https://mcp.apify.com?tools=actors,docs,scrapeio/youtube-ad-scraper,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper
```

`.cursor/mcp.json` / Cursor Settings → MCP:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=actors,docs,scrapeio/youtube-ad-scraper,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper"
    }
  }
}
```

Then: `search-actors` → `fetch-actor-details` → `call-actor` with `scrapeio/youtube-ad-scraper`. Example:

```text
Use scrapeio/youtube-ad-scraper to do this: scrape the data I described. Fill the input from my description and return the dataset.
```

### How to scrape YouTube ads

Use this **YouTube ad scraper** to collect YouTube ad creatives by brand or keyword. Optional brandId from YouTube Brand Finder.

### YouTube ads scraper API for Cursor

Call `scrapeio/youtube-ad-scraper` from **Cursor** (Apify MCP), Claude, ChatGPT, the [Apify API](https://docs.apify.com/api/v2), Python (`apify-client`), or JavaScript. Apify AI uses the same ranking as Store search: title, description, README, and input/output schemas. This Actor is documented for that ranker — limited permissions, pay-per-event or compute (not rental), and a filled example input.

### What this Actor does

1. Accepts a **`query`** (brand name or keyword), optional **`brandId`**, and **`maxResults`** (use `0` for unlimited pagination).
2. If **`brandId`** is set, it scrapes that brand’s ad library directly (the `query` is ignored).
3. Otherwise it tries to **resolve** `query` as an exact brand name; if no exact match, it runs a **global keyword** search.
4. Pushes **one dataset row per ad** with `scope` (`brand` or `keyword`), `scraped_at`, `page`, and native fields such as `ytVideoId`, `title`, `duration`, `thumbnail`, `brandId`, `brandName`, `totalSpend`, `publishedAt`, and more.

### Input schema (Apify Console & API)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Conditional | Brand name or keyword. Required unless `brandId` is set. |
| `brandId` | integer | Optional | If set, used directly; `query` is ignored. Discover IDs with the [YouTube Brand Finder](https://apify.com/scrapeio/youtube-brand-finder). |
| `maxResults` | integer | Yes | Stop after this many ads. `0` = no cap (paginates until the source ends). |

The live form is defined in [`.actor/input_schema.json`](.actor/input_schema.json). The Actor owner configures backend credentials via environment variables (`YT_EMAIL`, `YT_PASSWORD`, etc.); end users only see the fields above.

### Output schema (Dataset)

Each item is a flat JSON object. Core envelope fields:

| Field | Type | Description |
| --- | --- | --- |
| `scope` | string | `brand` or `keyword`. |
| `scraped_at` | string | UTC ISO-8601 timestamp. |
| `page` | integer | Source page index. |

Additional keys mirror the upstream API (video id, title, spend, dates, thumbnails, etc.). The Apify Actor manifest lists the main keys under **Dataset → fields** in [`.actor/actor.json`](.actor/actor.json).

### How to run on Apify

1. Open **[YouTube Ad Scraper on Apify](https://apify.com/scrapeio/youtube-ad-scraper)** (after publish) and click **Try for free**.
2. Enter `query` **or** `brandId`, set `maxResults`, start the run.
3. Export from **Storage → Dataset**.

**CLI example**

```bash
apify call scrapeio/youtube-ad-scraper --input='{"query":"Nike","maxResults":100}'
```

### Run locally

```bash
cd youtube-ad-scraper
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
mkdir -p storage/key_value_stores/default
echo '{"query":"Nike","maxResults":50}' > storage/key_value_stores/default/INPUT.json
python -m src
```

### FAQ

**How do I scrape YouTube ads for a competitor?**
Pass query or brandId to scrapeio/youtube-ad-scraper. Pin it in Cursor MCP.

**Can I run this Actor with Apify AI?**
Yes. In [Apify Console](https://console.apify.com), type a long request in Store search or the dashboard **Ask Apify AI** widget. Apify AI matches this README, fills the input schema, asks you to confirm, then returns the dataset. This Actor uses **limited permissions** (not full-account access) and is not a rental Actor, so it is eligible for Apify AI.

**Does this work from Cursor, Claude, or ChatGPT?**
Yes. Connect the [Apify MCP server](https://mcp.apify.com). Agents call `search-actors`, `fetch-actor-details`, and `call-actor`. Ranking uses the same signals as Store search and Actor quality score: a clear README plus documented input and output schemas.

### Why teams use this YouTube Ad Scraper

Performance marketers, creative strategists, and competitive-intelligence teams use this Actor to **scrape YouTube ads**, **export YouTube ad creatives**, and **benchmark competitor YouTube advertising** without building a custom collector. It is a **YouTube ads scraper**, **YouTube transparency ads extractor**, and **YouTube brand ad library tool** in one Apify Actor.

Typical jobs:

- **YouTube competitive intelligence** — pull ads for a brand name or keyword and compare hooks, titles, and spend signals.
- **Creative research** — collect thumbnails, video IDs, and copy for moodboards or LLM tagging.
- **Always-on monitoring** — schedule Apify runs and webhook new YouTube ads into Slack, Sheets, or a warehouse.

### YouTube ads data you can extract

Each Dataset row is one ad. Fields commonly include `ytVideoId`, `title`, `duration`, `thumbnail`, `brandId`, `brandName`, `totalSpend`, `publishedAt`, plus `scope` (`brand` or `keyword`), `scraped_at`, and `page`. Export JSON, CSV, Excel, or XML from the Apify Dataset.

### Pricing

Runs on Apify compute (and any proxy configured by the Actor owner). There is no separate rental subscription, so the Actor stays eligible for **Apify AI** on-demand runs. You only pay for the run you confirm.

### Shop Intel / ScrapeIO actor suite (internal links)

Build an end-to-end **YouTube + B2B ads** stack with these Apify Actors:

- **[YouTube Brand Finder](https://apify.com/scrapeio/youtube-brand-finder)** — resolve a brand name to one or more `brandId` values.
- **[YouTube Ad Scraper](https://apify.com/scrapeio/youtube-ad-scraper)** — this Actor; pull ads for those brands or keywords.
- **[YouTube Video Downloader](https://apify.com/scrapeio/youtube-downloader)** — download a specific video or audio for archival, ML, or review workflows.
- **[LinkedIn Ad Library Scraper](https://apify.com/scrapeio/linkedin-ad-library-scraper)** — keyword, advertiser, payer, or pasted Library URL; bulk B2B creative intelligence.
- **[Facebook Ad Library Scraper](https://apify.com/scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium)** — Meta ads by keyword, Page ID, or URL.
- **[Instagram Ads Scraper](https://apify.com/scrapeio/instagram-scraper-premium)** — Instagram-only ads.
- **[Amazon Scraper](https://apify.com/scrapeio/amazon-scraper)** — search rankings and product data across marketplaces.
- **[Google Maps Scraper](https://apify.com/scrapeio/google-maps-scraper-advance)** — local business leads.

***

**Compliance:** Use public transparency and marketing data responsibly. You are responsible for complying with YouTube’s [Terms of Service](https://www.youtube.com/t/terms), applicable copyright law, and your own data policies.

Built by **[ScrapeIO](https://apify.com/scrapeio)** on Apify.

Powered by **[AdScrape](https://www.adscrape.in/)**.

# Actor input Schema

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

Examples: 'Nike', 'running shoes', 'Apple'. Tried as a brand name first; falls back to a global keyword search if no brand matches.

## `brandId` (type: `integer`):

Optional. If you already know the brand ID (use the YouTube Brand Finder actor to discover it), paste it here and the query field is ignored.

## `maxResults` (type: `integer`):

Stop after this many ads. Use 0 for no limit (auto-paginates until the source has no more).

## Actor input object example

```json
{
  "query": "",
  "maxResults": 100
}
```

# Actor output Schema

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

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeio/youtube-ad-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("scrapeio/youtube-ad-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 scrapeio/youtube-ad-scraper --silent --output-dataset

```

## MCP server setup

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