# AdScout – Google & Meta Ad Library Scraper + AI Hooks (`kuttura_special/adscout`) Actor

Public ads from Google Ads Transparency (+ Meta Ad Library beta, free) in one schema. Archive media before links expire; AI hooks & briefs. $1.50/1k Google ads.

- **URL**: https://apify.com/kuttura_special/adscout.md
- **Developed by:** [Kuttura LLC](https://apify.com/kuttura_special) (community)
- **Categories:** Marketing, AI
- **Stats:** 2 total users, 1 monthly users, 33.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## AdScout – Google Ads Transparency & Meta Ad Library Scraper with AI Hook Analysis

> **DRAFT – not published. Pending owner approval.**

AdScout collects **public ad creatives** from official ad transparency libraries and returns them in **one normalized, cross-platform schema** — plus optional **media archiving** (source links expire) and **AI hook analysis** (transcript, hook line, hook type, pattern brief).

### Sources

| Platform | How | Coverage |
|---|---|---|
| Google Ads Transparency Center | Public, logged-out transparency data | Search, display, YouTube ads worldwide; text/image/video formats |
| Meta Ad Library — **Beta** | **Official Ad Library API, bring your own access token.** Off by default. **Meta ads are free.** | Non-political ads delivered in the EU/UK (DSA transparency) |
| TikTok | Not included in v1 (TikTok's terms and robots.txt do not allow automated collection of its ad library). TikTok's official Commercial Content API may be supported in a future version. | — |

Every platform has its own on/off switch. **Political and issue ads are excluded.**

### What you get per ad

`adId, platform, advertiserName, advertiserId, firstSeen, lastSeen, runDays, isActive, countries, format, creativeUrls, adCopy {headline, body}, landingDomain, libraryUrl, scrapedAt` and optionally `media` (archived file in the run's key-value store), `transcript, transcriptLanguage, durationSec, hookText, hookType`. A pattern brief is saved as `PATTERN_BRIEF` in the key-value store.

### Input

Keywords/brands, advertisers (Google `AR…` IDs, domains like `nike.com`, or Meta Page IDs), countries (ISO-2), date range, max ads per platform, platform switches, your Meta token, add-on switches.

### Meta (Beta): bring your own token

Meta is **off by default**. To use it, switch on *Meta Ad Library — Beta* and paste your own token. If the token is missing or invalid, AdScout skips Meta with a clear error message, the rest of the run continues, and **nothing is charged for Meta**.

Create an app at developers.facebook.com, complete identity verification for the Ad Library API, and paste a user access token. The token is a secret input, is used only to call Meta's API on your behalf, and is never logged or stored in the output.

### Pricing (pay per event)

| Event | Price |
|---|---|
| Run start | $0.02 |
| Google ad scraped | $0.0015 ($1.50 / 1,000) |
| Meta ad scraped | **Free** |
| Media archived (optional, Google ads) | $0.003 per ad |
| AI transcription (optional) | $0.025 per started minute |
| Hook analysis (optional) | $0.03 per ad |
| Pattern brief (optional) | $0.05 per run |

You are only charged for Google ads that were successfully saved and for add-ons that actually succeeded (e.g. no hook-analysis charge when an ad has no text or speech, no transcription charge for music-only videos). Meta ads are free; only AI add-ons on them are billed.

### Disclaimer

AdScout is an independent tool and is **not affiliated with, endorsed by, or sponsored by Google, Meta or TikTok**. It only reads **publicly available, logged-out ad transparency data** (and, for Meta, the official API using **your own** credentials, under Meta's terms that you accepted). It does not collect personal or contact data and excludes political ads. **You are responsible for using the data lawfully** and in line with the platforms' terms, copyright and data-protection laws (e.g. GDPR) in your jurisdiction. Ad creatives remain the property of their owners.

# Actor input Schema

## `keywords` (type: `array`):

Brand or product names. Google: matched to advertisers via the Transparency Center search. Meta: Ad Library search terms.

## `advertisers` (type: `array`):

Google advertiser IDs (AR…), advertiser domains (e.g. nike.com), or Meta Page IDs.

## `countries` (type: `array`):

e.g. US, DE. Meta non-political ads are only available for EU/UK countries (defaults to DE,FR).

## `dateFrom` (type: `string`):

YYYY-MM-DD

## `dateTo` (type: `string`):

YYYY-MM-DD

## `maxAds` (type: `integer`):

Hard cap per platform.

## `enableGoogle` (type: `boolean`):

On/off switch.

## `googleFormat` (type: `string`):

Only return this Google ad format.

## `enableMeta` (type: `boolean`):

BETA, off by default. Uses Meta's official Ad Library API with YOUR OWN access token. Meta ads are free (only AI add-ons are billed). Coverage: non-political ads delivered in the EU/UK. If the token is missing or invalid, Meta is skipped with a clear error and nothing is charged for Meta.

## `metaAccessToken` (type: `string`):

Your own Ad Library API token (developers.facebook.com, identity-verified). Stored as a secret; never logged.

## `enableTiktok` (type: `boolean`):

Not available in v1: TikTok's robots.txt and Terms forbid automated collection. TikTok's official Commercial Content API may be added in a future version.

## `saveMedia` (type: `boolean`):

Save each ad's image/thumbnail to the run's key-value store (source links expire). Billed per saved file.

## `analyzeHooks` (type: `boolean`):

Hook text and hook type per ad (from ad copy or the video transcript).

## `transcribeVideos` (type: `boolean`):

With hook analysis: AI transcription of Google video ads (YouTube-hosted). Billed per started minute.

## `maxVideoMinutes` (type: `integer`):

Longer videos are not transcribed.

## `generateBrief` (type: `boolean`):

One AI brief across all analyzed ads (requires hook analysis).

## `allowResidential` (type: `boolean`):

Use residential proxy only when Google rate-limits the direct connection and for YouTube media, capped below.

## `residentialCapMb` (type: `integer`):

Maximum residential traffic per run.

## Actor input object example

```json
{
  "keywords": [
    "nike"
  ],
  "maxAds": 5,
  "enableGoogle": true,
  "googleFormat": "all",
  "enableMeta": false,
  "enableTiktok": false,
  "saveMedia": false,
  "analyzeHooks": false,
  "transcribeVideos": true,
  "maxVideoMinutes": 3,
  "generateBrief": false,
  "allowResidential": false,
  "residentialCapMb": 20
}
```

# Actor output Schema

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

Advertiser, format, run dates, landing domain, hook.

## `full` (type: `string`):

All fields including creative URLs, transcripts and media.

## `files` (type: `string`):

Key-value store with archived media.

## `patternBrief` (type: `string`):

AI brief (only when generateBrief=true).

## `runSummary` (type: `string`):

Per-platform counts, errors, charges and proxy usage.

# 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 = {
    "keywords": [
        "nike"
    ],
    "maxAds": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("kuttura_special/adscout").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 = {
    "keywords": ["nike"],
    "maxAds": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("kuttura_special/adscout").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 '{
  "keywords": [
    "nike"
  ],
  "maxAds": 5
}' |
apify call kuttura_special/adscout --silent --output-dataset

```

## MCP server setup

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

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/OlRAtXpjvoe7AQOEd/builds/IzanP2i51DNj0ZAwA/openapi.json