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

Scrape Snapchat ads from the official Ads Gallery API + Political Ads Library — creatives, impressions, targeting, and spend. MCP/API-ready.

- **URL**: https://apify.com/khadinakbar/snapchat-ads-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Social media, MCP servers, AI
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 ad scrapeds

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/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 Scraper

Snapchat Ads Scraper is an Apify Actor for marketers, researchers, journalists, compliance teams, and AI agents that need one structured record per Snapchat ad or archive row. It accepts a single JSON input object and returns one flat record per item, depending on the selected mode. The output can include advertiser name, creator name, headline, call to action, media URL, landing URL, impressions, spend, targeting, and review status when Snapchat provides those fields. The Actor is usable through Apify, the Apify API, and Apify MCP, and it writes results to the default dataset for programmatic readback.

### Best fit and connected workflows

This Actor fits workflows that begin with a brand name, creator handle, or political search term and continue into structured Snapchat ad records for review, analysis, or automation.

- Use `search` when you have a paying advertiser name and want Ads Gallery records for a brand in EU and EEA markets.
- Use `creator` when you have a creator name and want sponsored or branded content tied to that public profile.
- Use `political` when you need records from the worldwide Political Ads Library, including spend and targeting fields.
- If your workflow starts in another advertising transparency surface, this Actor works well as the Snapchat-specific step in a broader cross-platform research pipeline.

### Practical scenario

A media analyst wants to review ads from a cosmetics brand in France and Germany. They start with the advertiser name, select `search` mode, add `fr` and `de` to `countries`, and set `status` to `ACTIVE`. The returned records include fields such as `headline`, `callToAction`, `mediaDownloadUrl`, `landingUrl`, `impressionsTotal`, and `targeting`. The analyst uses those fields to compare creative hooks and then opens the landing URLs for manual review.

### Input fields

| Field | Type | Mode | Description |
| --- | --- | --- | --- |
| `mode` | string | all | Selects the Snapchat data source: `search`, `creator`, or `political`. Defaults to `search`. |
| `advertiserName` | string | search | Paying advertiser / brand name for Ads Gallery search. |
| `countries` | array\[string] | search | EU/EEA country codes for Ads Gallery search. Empty selects the supported country set. |
| `status` | string | search | Ads Gallery delivery status filter: `ANY`, `ACTIVE`, or `PAUSED`. |
| `startDate` | string | search | Lower bound for Ads Gallery delivery date, in ISO-8601 format. |
| `endDate` | string | search | Upper bound for Ads Gallery delivery date, in ISO-8601 format. |
| `creatorName` | string | creator | Creator / public profile name for creator mode. |
| `politicalYears` | array\[string] | political | Political Ads Library archive years to download. |
| `politicalCountry` | string | political | Optional 2-letter country filter for political records. |
| `politicalSearchTerm` | string | political | Optional keyword filter for political records. |
| `maxResults` | integer | all | Maximum number of records to return and bill for. |
| `proxyConfiguration` | object | all | Proxy settings, with Apify Proxy as the default. |

#### Focused input example

```json
{
  "mode": "search",
  "advertiserName": "Nike",
  "countries": ["fr", "de"],
  "status": "ACTIVE",
  "startDate": "2025-01-01",
  "maxResults": 50
}
```

### Output fields

The Actor stores flat records in the default dataset. The output schema points to the dataset items endpoint, and each record may include fields from the selected source.

| Field | Type | Description |
| --- | --- | --- |
| `source` | string | Record origin such as `ads_gallery`, `creator_content`, or `political`. |
| `id` | string | Snapchat ad or record identifier. |
| `name` | string | Internal ad or creative name. |
| `advertiserName` | string | Paying advertiser from Ads Gallery records. |
| `payingAdvertiserName` | string | Paying advertiser from Political Ads Library records. |
| `adAccountName` | string | Ad account name. |
| `profileName` | string | Public Snapchat profile or handle. |
| `creatorName` | string | Creator handle in creator mode. |
| `creatorUrl` | string | Creator profile URL in creator mode. |
| `sponsorName` | string | Sponsoring brand in creator mode. |
| `sponsorUrl` | string | Sponsor profile URL in creator mode. |
| `contentType` | string | Sponsored content type in creator mode. |
| `contentUrl` | string | Sponsored content URL in creator mode. |
| `thumbnailUrl` | string | Content thumbnail URL in creator mode. |
| `status` | string | Delivery status. |
| `creativeType` | string | Creative format, such as `WEB_VIEW`. |
| `adType` | string | Ad type, such as `REMOTE_WEBPAGE`. |
| `headline` | string | Ad headline text. |
| `callToAction` | string | CTA label, such as `SHOP NOW`. |
| `languages` | array | Creative languages. |
| `topSnapMediaType` | string | Top-snap media type, such as `VIDEO` or `IMAGE`. |
| `mediaDownloadUrl` | string | Direct CDN media download link. |
| `landingUrl` | string | Web view or landing page URL. |
| `creativeUrl` | string | Creative URL in political mode. |
| `startDate` | string | Delivery start, ISO-8601. |
| `endDate` | string | Delivery end, ISO-8601. |
| `impressionsTotal` | integer | Total impressions in Ads Gallery mode. |
| `impressions` | integer | Impressions bucket in political mode. |
| `impressionsByCountry` | object | Non-zero impressions keyed by ISO country. |
| `spend` | number | Reported spend in political mode. |
| `currencyCode` | string | Spend currency in political mode. |
| `countryCode` | string | Country in political mode. |
| `organizationName` | string | Funding organization in political mode. |
| `candidateBallotInfo` | string | Candidate or ballot info in political mode. |
| `committeeName` | string | Committee name in political mode. |
| `advertisingJurisdiction` | string | Jurisdiction in political mode. |
| `gender` | string | Gender targeting. |
| `ageBracket` | string | Age bracket targeting in political mode. |
| `regionsIncluded` | string | Included regions in political mode. |
| `interests` | string | Interest targeting in political mode. |
| `segments` | string | Audience segments in political mode. |
| `language` | string | Targeted language in political mode. |
| `osType` | string | OS targeting in political mode. |
| `targeting` | object | Simplified Ads Gallery targeting such as age, gender, and devices. |
| `reviewStatus` | string | Snapchat review status. |

#### Illustrative dataset record

```json
{
  "source": "ads_gallery",
  "id": "1e02cbfd-033c-419b-af83-8ab4dabf68de",
  "advertiserName": "Nike, Inc.",
  "adAccountName": "Nike EMEA - Initiative Womens",
  "profileName": "jumpman23",
  "status": "ACTIVE",
  "creativeType": "WEB_VIEW",
  "adType": "REMOTE_WEBPAGE",
  "headline": "La Air Jordan 40 est arrivée",
  "callToAction": "SHOP NOW",
  "topSnapMediaType": "VIDEO",
  "mediaDownloadUrl": "https://cf-st.sc-cdn.net/d/...",
  "landingUrl": "https://www.nike.com/fr/w/...",
  "startDate": "2025-07-11T22:00:00.000Z",
  "impressionsTotal": 2437373,
  "impressionsByCountry": {
    "fr": 2437373
  },
  "targeting": {
    "minAge": "18"
  },
  "reviewStatus": "APPROVED"
}
```

### How it works

This Actor uses Snapchat's public ad transparency surfaces in three modes:

- `search` queries the Ads Gallery for brand or advertiser searches in EU and EEA markets.
- `creator` pulls sponsored and branded content tied to a creator name.
- `political` downloads the Political Ads Library archive and filters rows by year, country, and keyword when those inputs are provided.

The live manifest describes the Actor as HTTP-only and no-auth, and the dataset schema exposes a single flat record shape with fields that vary by source. The output schema points readers to the default dataset items endpoint, so downstream tools can read the results directly.

### Pricing

This Actor uses Pay per event pricing plus Apify platform usage. Open the live Pricing tab in the Apify Console for the current pricing details for your account and run.

Billing events are defined by the returned records:

- Actor start: one event per run
- Ad scraped: one event for each Ads Gallery or creator content item returned
- Political ad scraped: one event for each Political Ads Library record returned

Example in words: if a run returns one hundred Ads Gallery records, the execution includes one Actor start event and one hundred ad scraped events. If you run the same Actor in political mode and return fifty political records, the execution includes one Actor start event and fifty political ad scraped events for that run.

### Use with AI agents (MCP)

This Actor is available as an Apify Actor usable through Apify MCP. The exact Actor identity is `khadinakbar/snapchat-ads-scraper`.

Tool description: fetch Snapchat ad transparency records from Ads Gallery, creator content, or the Political Ads Library and return structured dataset rows that can be read programmatically.

> Search Snapchat Ads Gallery for Nike in France and Germany, then return the ad records with headline, CTA, media URL, landing URL, impressions, and targeting.

Output interpretation: `source` identifies which Snapchat surface produced each record, and the remaining fields reflect the selected mode. Provenance lives in the returned dataset rows created by the Actor run. Ads Gallery requests are paginated through Snap's public cursor flow until `maxResults` is reached, while political mode reads yearly archive files selected in the input. To manage cost, set `maxResults` before the run so billing stops at the selected record count. The returned dataset can be read from the default dataset items endpoint, which is the same output location used by Apify API clients and MCP workflows.

### Apify API example

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const run = await client.actor('khadinakbar/snapchat-ads-scraper').call({
  mode: 'search',
  advertiserName: 'Nike',
  countries: ['fr', 'de'],
  status: 'ACTIVE',
  maxResults: 10,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems({
  clean: true,
  format: 'json',
});

console.log(items);
```

### Best results and outcome guidance

Use the input that matches the Snapchat surface you already know.

- Start with `advertiserName` for commercial Ads Gallery research.
- Use `creatorName` when the starting point is a public creator profile.
- Use `politicalYears` with `politicalCountry` or `politicalSearchTerm` when the task is archive analysis.
- Keep `maxResults` aligned with the number of records you want to analyze.
- Review `mediaDownloadUrl`, `landingUrl`, `headline`, `callToAction`, and `targeting` together when comparing creative and delivery details.

### Focused standalone workflow

This Actor is designed as a focused standalone workflow.

### Design note

I found that the overview view is intentionally source-agnostic: it highlights `source`, `advertiserName`, `payingAdvertiserName`, `headline`, `callToAction`, `status`, `impressionsTotal`, `spend`, `currencyCode`, `startDate`, `mediaDownloadUrl`, and `landingUrl` across all modes.

### FAQ

**When should I use `search` instead of `creator`?**\
Use `search` when the starting point is a paying advertiser or brand name. Use `creator` when the starting point is a creator handle or public profile name.

**What does `political` add that the other modes may not?**\
Political mode returns records from the Political Ads Library and includes spend, currency, and richer targeting fields such as country, age bracket, gender, interests, and segments when they are present.

**Which countries are available in Ads Gallery search?**\
The input schema lists the supported EU and EEA country codes in the `countries` field, and leaving the field empty selects the supported country set.

**How do I control run size?**\
Set `maxResults` to the number of records you want returned and billed.

**Can I use this Actor through Apify MCP?**\
Yes. It is an Apify Actor usable through Apify MCP, and the Actor identity is `khadinakbar/snapchat-ads-scraper`.

### Responsible use

This Actor reads public Snapchat ad transparency sources. Use the data in ways that respect applicable laws, platform terms, and privacy obligations. Review the returned records in context before making decisions based on them.

# Actor input Schema

## `mode` (type: `string`):

Which Snapchat data source to scrape. 'search' queries the official EU Ads Gallery for a brand's commercial ads; 'creator' pulls sponsored/branded content by a creator name; 'political' downloads the worldwide Political Ads Library archive with spend and targeting. Defaults to 'search'. This is NOT a Snapchat profile, Story, or Spotlight scraper.

## `advertiserName` (type: `string`):

Paying advertiser to search in the Ads Gallery (e.g. 'Nike'). Required in 'search' mode; matches Snapchat's paying advertiser name. The Ads Gallery cannot list all advertisers at once, so a brand name is needed. NOT a Snapchat username — for creators use creatorName.

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

EU/EEA countries (2-letter ISO codes) to include in 'search' mode. The Ads Gallery only covers ads delivered in these markets in the last 12 months. Defaults to all 27 supported countries when left empty. Codes outside this list are rejected by Snapchat.

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

Filter Ads Gallery results by delivery status. 'ANY' returns both active and paused ads; 'ACTIVE' only currently delivering ads; 'PAUSED' only stopped ads. Defaults to 'ANY'. Applies only to 'search' mode.

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

Only return Ads Gallery ads delivered on or after this date. Use ISO-8601 format (e.g. '2025-01-01'). Leave empty for no lower bound. Applies only to 'search' mode.

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

Only return Ads Gallery ads delivered on or before this date. Use ISO-8601 format (e.g. '2025-12-31'). Leave empty for no upper bound. Applies only to 'search' mode.

## `creatorName` (type: `string`):

Creator / public profile name for 'creator' mode (e.g. 'kyliejenner'). Returns sponsored and branded content associated with that creator. Required when mode = 'creator'; ignored otherwise. NOT a brand — for brands use advertiserName.

## `politicalYears` (type: `array`):

Years of the Political Ads Library archive to download in 'political' mode. Each year is a separate official Snap CSV archive of political/advocacy ads worldwide. Defaults to \['2025']. Add multiple years to combine, e.g. \['2024','2025'].

## `politicalCountry` (type: `string`):

Optional 2-letter country filter for 'political' mode (e.g. 'us'). Keeps only rows whose CountryCode matches. Leave empty for all countries. Case-insensitive.

## `politicalSearchTerm` (type: `string`):

Optional free-text filter for 'political' mode; keeps only rows containing this term (advertiser, organization, candidate, etc.). Case-insensitive substring match across all columns. Leave empty for no filter.

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

Maximum number of records to return and bill for across all pages and years. Hard cap is 50000. Defaults to 100. Billing stops once this number is reached.

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

Proxy settings. Defaults to Apify Proxy. Both data sources are public with no anti-bot, so datacenter proxy is sufficient; proxy mainly spreads request volume. Leave at default unless you have a reason to change it.

## Actor input object example

```json
{
  "mode": "search",
  "advertiserName": "Nike",
  "countries": [],
  "status": "ANY",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "creatorName": "kyliejenner",
  "politicalYears": [
    "2025"
  ],
  "politicalCountry": "us",
  "politicalSearchTerm": "senate",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `ads` (type: `string`):

Scraped Snapchat ad records (Ads Gallery, creator content, or political).

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

Normalized terminal outcome for agent and API clients.

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

Detailed terminal outcome, counts, and charge events.

# 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 = {
    "advertiserName": "Nike",
    "maxResults": 100,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/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 = {
    "advertiserName": "Nike",
    "maxResults": 100,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/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 '{
  "advertiserName": "Nike",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call khadinakbar/snapchat-ads-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/pNrBHdXl6lOdDMiLu/builds/3MXsR33bHVtHpuXvY/openapi.json