# 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. - **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, 1 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 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Scrape **Snapchat ads** from the two official, public Snap data sources in one actor — no login, no cookies, no anti-bot. Pull competitor ad creatives, impressions, targeting, and call-to-actions from the **Snap Ads Gallery**, and pull political/advocacy ad **spend and targeting** from the **Snap Political Ads Library**. Built HTTP-first on Snap's own documented endpoints, so it is fast and reliable, and it is **MCP-ready** for AI agents (Claude, ChatGPT, Gemini). ### What it does Three modes, picked with a single `mode` field: | Mode | Source | Use it for | |------|--------|------------| | `search` | Snap **Ads Gallery** API (EU, last 12 months) | Competitor creative intelligence — every ad a brand runs, with headline, CTA, media, impressions, and targeting | | `creator` | Snap **sponsored content** API | Influencer / branded-content research by creator name | | `political` | Snap **Political Ads Library** (worldwide, 2018–2026) | Political ad transparency — **spend**, currency, impressions, and granular geo/interest targeting | ### When to use it - **Performance marketers & agencies** reverse-engineering a competitor's Snapchat creative strategy and hooks. - **Market & competitive-intel researchers** tracking which brands are active in EU markets. - **Journalists, academics, and compliance teams** auditing political ad spend and targeting. - **AI agents** that need a clean, structured Snapchat ad tool call. **Do NOT use it for** Snapchat user profiles, Stories, Spotlight, or private account data — this actor only reads Snap's public ad transparency surfaces. ### Output One flat JSON record per ad. Example (Ads Gallery / `search` mode): ```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", "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" } ```` Example (Political Ads Library / `political` mode) — note the **spend** field the Ads Gallery does not provide: ```json { "source": "political", "id": "0001abcd...", "payingAdvertiserName": "Example Committee", "organizationName": "Example Org", "spend": 1450.0, "currencyCode": "USD", "impressions": 250000, "countryCode": "united states", "startDate": "2024-09-01", "endDate": "2024-11-05", "gender": "MALE,FEMALE", "ageBracket": "18+", "interests": "Politics", "candidateBallotInfo": "..." } ``` ### Pricing — Pay Per Event You pay only for what you pull. No monthly rental. | Event | Price | |-------|-------| | Actor start | $0.001 per run | | Ad scraped (Ads Gallery / creator) | **$0.005** per ad | | Political ad scraped | **$0.007** per record | Example: scraping 500 of a competitor's Ads Gallery ads costs about **$2.50**. Set `maxResults` to cap spend on every run. ### Input | Field | Mode | Description | |-------|------|-------------| | `mode` | all | `search`, `creator`, or `political` | | `advertiserName` | search | Brand / paying advertiser, e.g. `Nike` (required for `search`) | | `countries` | search | EU ISO-2 codes; defaults to all 27 | | `status` | search | `ANY`, `ACTIVE`, or `PAUSED` | | `startDate` / `endDate` | search | ISO-8601 delivery date bounds | | `creatorName` | creator | Creator handle, e.g. `kyliejenner` | | `politicalYears` | political | Archive years, e.g. `["2024","2025"]` | | `politicalCountry` | political | Optional ISO-2 country filter | | `politicalSearchTerm` | political | Optional keyword filter | | `maxResults` | all | Cap on records and billing (default 100) | #### Example: competitor ad intelligence ```json { "mode": "search", "advertiserName": "Nike", "countries": ["fr", "de", "es"], "status": "ACTIVE", "maxResults": 200 } ``` #### Example: political ad spend research ```json { "mode": "political", "politicalYears": ["2024", "2025"], "politicalCountry": "us", "politicalSearchTerm": "senate", "maxResults": 1000 } ``` ### Use via API / MCP The actor is exposed in the Apify MCP server as `apify--snapchat-ads-scraper`. A single, narrow input and flat structured output make it an easy tool call for AI agents doing competitive or political ad research. It is also callable through the standard Apify API and client SDKs. ### How it works - **Ads Gallery** (`search`, `creator`) hits Snap's documented public endpoint `adsapi.snapchat.com/v1/ads_library` — no authentication required. Results are paginated automatically via Snap's cursor until `maxResults` is reached. - **Political** downloads Snap's official yearly archive (`PoliticalAds.zip`) from Google Cloud Storage, unzips it in memory, parses the CSV, and applies your optional country / keyword filters. Requests retry with exponential backoff on rate limits, and the run reports an honest terminal status — it fails loudly on upstream errors rather than silently returning an empty dataset. ### Coverage & limitations - The **Ads Gallery** is Snap's EU ad transparency surface: it covers ads **delivered in the EU/EEA in the last 12 months**. It does **not** include ad spend. - The **Political Ads Library** is **worldwide and historical (2018–2026)** and **does** include spend and detailed targeting. - Creator/sponsored-content coverage depends on what Snap exposes for a given creator and may be sparse. - Snap controls these endpoints and their fields; output adapts to what Snap returns. ### Frequently asked questions **Do I need a Snapchat account, login, or cookies?** No. Both sources are public. **Can I get commercial (non-political) ad spend?** Snap does not publish commercial spend; the Ads Gallery exposes impressions and targeting only. Spend is available for political ads via `political` mode. **Which countries does `search` cover?** The 27 EU/EEA markets: at, be, bg, hr, cy, cz, dk, ee, fi, fr, de, el, hu, ie, it, lv, lt, lu, mt, nl, pl, pt, ro, sk, si, es, se. **How do I cap costs?** Set `maxResults`. Billing stops at that number. ### Related actors - `meta-ad-library-scraper` — Meta (Facebook/Instagram) ad creatives - `tiktok-ads-scraper` — TikTok Creative Center top ads - `google-ads-transparency-scraper` — Google Ads creatives ### Legal This actor collects only publicly available ad transparency data published by Snap Inc. Use it in compliance with Snapchat's Terms of Service and all applicable laws (including data-protection rules). You are responsible for how you use the scraped data. Not affiliated with or endorsed by Snap Inc. # 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). # 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 '' with your token const client = new ApifyClient({ 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 '' with your token. client = ApifyClient("") # 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 " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Snapchat Ads Scraper", "description": "Scrape Snapchat ads from the official Ads Gallery API + Political Ads Library — creatives, impressions, targeting, and spend.", "version": "0.1", "x-build-id": "7vQUslb6s3etOfKeE" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~snapchat-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-snapchat-ads-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/khadinakbar~snapchat-ads-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-snapchat-ads-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/khadinakbar~snapchat-ads-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-snapchat-ads-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Mode", "enum": [ "search", "creator", "political" ], "type": "string", "description": "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.", "default": "search" }, "advertiserName": { "title": "Advertiser / brand name", "type": "string", "description": "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": { "title": "Countries (Ads Gallery)", "type": "array", "description": "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.", "items": { "type": "string", "enum": [ "at", "be", "bg", "hr", "cy", "cz", "dk", "ee", "fi", "fr", "de", "el", "hu", "ie", "it", "lv", "lt", "lu", "mt", "nl", "pl", "pt", "ro", "sk", "si", "es", "se" ] }, "default": [] }, "status": { "title": "Ad status (Ads Gallery)", "enum": [ "ANY", "ACTIVE", "PAUSED" ], "type": "string", "description": "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.", "default": "ANY" }, "startDate": { "title": "Start date (Ads Gallery)", "type": "string", "description": "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": { "title": "End date (Ads Gallery)", "type": "string", "description": "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": { "title": "Creator name (Creator mode)", "type": "string", "description": "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": { "title": "Years (Political mode)", "type": "array", "description": "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'].", "items": { "type": "string", "enum": [ "2018", "2019", "2020", "2021", "2022", "2023", "2024", "2025", "2026" ] }, "default": [ "2025" ] }, "politicalCountry": { "title": "Country filter (Political mode)", "type": "string", "description": "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": { "title": "Keyword filter (Political mode)", "type": "string", "description": "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": { "title": "Max results", "minimum": 1, "maximum": 50000, "type": "integer", "description": "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.", "default": 100 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "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.", "default": { "useApifyProxy": true } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```