# 👻 Snapchat Ads Scraper (`scrapeflow/snapchat-ads-scraper`) Actor

Scrape the Snapchat Ads Library by advertiser / brand name. Get ad creatives, headlines, impressions, media download links, and full ad metadata at scale.

- **URL**: https://apify.com/scrapeflow/snapchat-ads-scraper.md
- **Developed by:** [ScrapeFlow](https://apify.com/scrapeflow) (community)
- **Categories:** Automation, Lead generation, Social media
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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

## 👻 Snapchat Ads Library Scraper

Scrape the **Snapchat Ads Library** by advertiser / brand name and pull every
ad creative, headline, impression count, media download link, and the rest of
the public ad metadata — at scale, in real time.

### Why Choose Us?

- 🧠 **Bulk advertiser input** — feed in a list of brand names and the actor
  scrapes them one by one, tagging each result with the search query.
- 🛡️ **Automatic proxy fallback** — direct → datacenter → residential (with
  3 retries on residential). You don't have to think about blocks.
- 💾 **Live saving** — every ad is pushed to the output table as soon as it
  is fetched, so a crash mid-run still leaves you with usable data.
- 🌍 **EU-country & date filters** — narrow to a single country or date range.
- 📡 **Status filter** — ACTIVE only, PAUSED only, or both.
- ⚡ **No browser** — pure HTTP, fast and cheap.

### Key Features

- 🔎 Bulk search by `paying_advertiser_name`
- 🎬 Returns ad ID, name, ad type, brand, headline, impressions, media
  download URL, media type, status, and start date
- ⬇️ Direct download links to top-Snap media (image or video)
- 🟢 Filter by ACTIVE / PAUSED
- 🌍 Filter by EU country code
- 📅 Filter by date range
- 🛡️ Built-in rate-limit handling with proxy escalation
- 📊 Per-search-query tagging in every output row

### Input

```json
{
  "searchQueries": ["Ikea", "Nike"],
  "maxItems": 30,
  "country": "FR",
  "status": "ACTIVE",
  "startDate": "2025-01-01",
  "endDate": "2026-05-16",
  "proxyConfiguration": { "useApifyProxy": false }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `searchQueries` | array of strings | ✅ | Advertiser / brand names. Bulk supported. Use `""` to fetch all ads. |
| `maxItems` | integer | ❌ | Max ads per query. Default `30`. |
| `country` | string | ❌ | EU ISO-2 country code (e.g. `FR`, `DE`). Empty = all countries. |
| `status` | string | ❌ | `ACTIVE`, `PAUSED`, or empty for both. |
| `startDate` | string | ❌ | `YYYY-MM-DD` — only ads whose `start_date` is ≥ this. |
| `endDate` | string | ❌ | `YYYY-MM-DD` — only ads whose `start_date` is ≤ this. |
| `proxyConfiguration` | object | ❌ | Standard Apify proxy editor. Defaults to no proxy. |

### Output

Each row in the dataset:

```json
{
  "searchQuery": "Ikea",
  "id": "ded3fe4b-8326-4423-bdfb-8d956de682b5",
  "adName": "Offre food 1 v2",
  "adType": "STORY",
  "payingAdName": "Ikea France",
  "accountName": "IKEA Global",
  "profileLogoUrl": "https://cf-st.sc-cdn.net/...",
  "profileName": "IKEA France",
  "brandName": "IKEA",
  "headline": "Menu étudiant au restaurant",
  "totalImpressions": 999232,
  "adStatus": "PAUSED",
  "snapMediaDownloadLink": null,
  "snapMediaType": null,
  "startDate": "2025-07-16T12:00:57.000Z"
}
```

| Field | Description |
|-------|-------------|
| `searchQuery` | The advertiser / brand keyword you searched for |
| `id` | Snapchat ad UUID |
| `adName` | Internal ad name from the advertiser |
| `adType` | `SNAP_AD`, `STORY`, `REMOTE_WEBPAGE`, `DEEP_LINK`, … |
| `payingAdName` | Paying advertiser entity |
| `accountName` | Ad account name on Snapchat |
| `profileLogoUrl` | Logo of the Snapchat profile that owns the ad |
| `profileName` | Display name of the profile |
| `brandName` | Brand string (falls back to first word of account name) |
| `headline` | Ad headline shown to viewers |
| `totalImpressions` | Lifetime impressions |
| `adStatus` | `ACTIVE` or `PAUSED` |
| `snapMediaDownloadLink` | Direct download link for the top-Snap media |
| `snapMediaType` | `IMAGE` or `VIDEO` |
| `startDate` | First-served timestamp (ISO 8601) |

### 🚀 How to Use (Apify Console)

1. Log in at <https://console.apify.com> → **Actors**.
2. Open **👻 Snapchat Ads Library Scraper**.
3. Enter one or more advertiser names in **Search Queries**.
4. (Optional) Pick a country, status, or date range.
5. Click **Start**.
6. Watch the logs — every ad is logged with brand, impressions, and headline.
7. Open the **Output** tab when the run completes.
8. Export to JSON / CSV / XLSX.

### 🤖 Use via API

```bash
curl -X POST "https://api.apify.com/v2/acts/<ACTOR_ID>/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "searchQueries": ["Ikea"],
       "maxItems": 50,
       "country": "FR",
       "status": "ACTIVE"
     }'
```

### Best Use Cases

- 🕵️ Competitor ad intelligence on Snapchat
- 🎨 Creative inspiration — see what creatives a brand is actually running
- 📈 Tracking impressions of a specific advertiser over time
- 🧪 Market research across EU countries
- 📚 Building ad-library datasets for ML / analytics

### Pricing

This actor uses Apify **Pay-per-event**. You pay per ad pushed to the dataset
(billed as the synthetic `apify-default-dataset-item` event) plus the small
`apify-actor-start` event. No platform usage is passed on by default.

### Frequently Asked Questions

**Do I need to be logged in to Snapchat?**
No. The Snapchat Ads Library is public and the actor calls it without auth.

**Can I search by ad URL?**
The library exposes ads by advertiser name, not by ad URL. Use the
`searchQueries` field with the advertiser / brand name.

**What happens if I get rate-limited?**
Snapchat returns `error_code: E1009` when an IP is being throttled. The actor
detects this, falls back to a datacenter proxy, then to a residential proxy
(retrying up to 3 times), and once residential is engaged it stays engaged.

**Are EU-only results a hard limit?**
Yes — the Snapchat Ads Library currently only exposes ads served in the EU.
Leaving `country` empty searches across the EU.

**Why is the dataset growing while the run is in progress?**
The actor uses `Actor.push_data` live, so each ad lands in the output table
the moment it's scraped — a crash partway through still leaves usable data.

### Support and Feedback

Open an issue on the Actor page or contact **dev.scraperengine@gmail.com**.

### Cautions / Legal

- Data is collected only from the **publicly available** Snapchat Ads Library.
- The end user is responsible for legal compliance (GDPR, CCPA, target-site
  ToS, etc.).
- Be a good citizen — keep `maxItems` reasonable to avoid hammering Snap's
  infrastructure.

# Actor input Schema

## `searchQueries` (type: `array`):

🏷️ Enter one or more **advertiser / brand names** to search the Snapchat Ads Library for (e.g. `Ikea`, `Nike`, `McDonald's`). Bulk input is fully supported — every keyword is processed independently and its results are tagged with the search query in the output.

💡 Use an empty string `""` as a single entry to fetch **all ads** in the library (filtered only by country / date / status).

## `maxItems` (type: `integer`):

🎯 Maximum number of ads to fetch **per search keyword**. Higher numbers = more data and longer runtime. Snapchat paginates internally; the actor follows the cursor until this limit is reached or no more ads are available.

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

🇪🇺 Restrict results to ads served in a single EU country. Leave empty to include **all countries**.

## `status` (type: `string`):

🟢 Filter by the current delivery status of the ad. Choose **Any** to include both active and paused ads.

## `startDate` (type: `string`):

📆 Only return ads with a `start_date` **on or after** this date (format: `YYYY-MM-DD`). Leave empty for no lower bound.

## `endDate` (type: `string`):

📆 Only return ads with a `start_date` **on or before** this date (format: `YYYY-MM-DD`). Leave empty for no upper bound.

## `proxyConfiguration` (type: `object`):

🛡️ By default the actor runs **without a proxy**. If Snapchat rate-limits or rejects the request, the actor automatically falls back to a **datacenter proxy**, then to a **residential proxy** (with up to **3 retries** on residential). Once residential is engaged, it stays engaged for the rest of the run.

## Actor input object example

```json
{
  "searchQueries": [
    "Ikea"
  ],
  "maxItems": 10,
  "country": "",
  "status": "",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "searchQueries": [
        "Ikea"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeflow/snapchat-ads-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 = {
    "searchQueries": ["Ikea"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scrapeflow/snapchat-ads-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "Ikea"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scrapeflow/snapchat-ads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scrapeflow/snapchat-ads-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/fXvniiVcJvOBgieUW/builds/y6f0ROogBFfzrhQ5G/openapi.json