# Snapchat Spotlight Scraper (`khadinakbar/snapchat-spotlight-scraper`) Actor Scrape Snapchat Spotlight videos from the trending discovery feed by country or from specific Spotlight URLs. Returns views, shares, boosts, recommends, comments, creator, sound, AI caption, hashtags, and the video download URL. HTTP-only, no cookies. MCP-ready. - **URL**: https://apify.com/khadinakbar/snapchat-spotlight-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, MCP servers, Agents - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.00 / 1,000 scraped spotlight videos 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 Spotlight Scraper — Trending Feed & URLs Scrape **Snapchat Spotlight** videos three ways: pull the **trending discovery feed** for any country (no URLs needed), scrape **specific Spotlight URLs**, or get a **creator's Spotlight videos by username**. Returns full engagement metrics, creator, sound, AI captions, hashtags, and the direct video download URL. HTTP‑only, no login, no cookies. MCP‑ready for AI agents. ### What it does Most Snapchat Spotlight scrapers only accept a list of URLs you already have. This one adds **discovery**: point it at a country and it returns that country's live trending Spotlight videos — fully enriched — without a single URL. You can still pass exact URLs when you need a specific video. - **Trending mode** — scrape the live Spotlight feed for a chosen country (US, GB, IN, PK, FR, DE, BR, and more). - **URLs mode** — scrape one or more `snapchat.com/spotlight/` links directly. - **Username mode** — get a creator's public Spotlight videos by handle (e.g. `mrbeast`). Uses the ScrapeCreators provider; no residential proxy required. ### When to use it - Track viral short‑video trends and sounds on Snapchat by country. - Benchmark creator performance (views, boosts, shares, recommends). - Feed structured Spotlight data to an AI agent, dashboard, or content pipeline. - Build trend reports without manually collecting URLs. Not for Snapchat **profiles** (use a Snapchat Profile Scraper), private content, stories, lenses, or DMs. > **Username mode** is provider-backed: the actor owner must set a `SCRAPECREATORS_API_KEY` environment variable (Console → Settings → Environment variables). Trending and URL modes need no key. ### Output — one row per video | Field | Description | |---|---| | `spotlightId`, `spotlightUrl` | Video ID and canonical Spotlight URL | | `creatorUsername`, `creatorName`, `creatorUrl`, `creatorFollowerCount` | Creator identity and reach | | `title`, `description`, `caption` | Video title, description, on‑screen caption | | `aiTitle`, `aiDescription`, `aiKeywords` | Snapchat's own AI‑generated title, summary, and keyword tags | | `hashtags` | Hashtags on the video | | `soundName`, `soundCreator` | Sound / music used and its creator | | `viewCount`, `shareCount`, `commentCount`, `boostCount`, `recommendCount` | Full public engagement metrics | | `durationMs`, `width`, `height` | Video length and dimensions | | `uploadedAt`, `isSponsored` | Upload time (ISO 8601) and sponsored flag | | `thumbnailUrl`, `previewUrl`, `videoUrl`, `transcriptUrl` | Thumbnail, preview, direct video download, and transcript URLs | | `country`, `mode`, `sourceUrl`, `runId`, `scrapedAt` | Run context | ### Pricing — pay per result | Event | Price | |---|---| | Actor start | $0.00005 | | Per Spotlight video saved | **$0.004** | A typical 25‑video trending run costs about **$0.10**. You are billed only for videos actually saved to the dataset. Both pay‑per‑event and platform usage billing are available. ### Input ```json { "mode": "trending", "country": "US", "maxResults": 25, "includeRawData": false } ```` URL mode: ```json { "mode": "urls", "spotlightUrls": [ "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAY..." ], "maxResults": 50 } ``` | Input | Type | Default | Notes | |---|---|---|---| | `mode` | enum `trending` | `urls` | `username` | `trending` | What to scrape | | `country` | string (ISO‑2) | `US` | Trending feed country (also sets proxy country) | | `proxyType` | enum `auto` | `residential` | `datacenter` | `auto` | Proxy for trending/urls. `auto` = residential then datacenter fallback | | `spotlightUrls` | array | `[]` | Required when `mode` is `urls` | | `usernames` | array | `[]` | Required when `mode` is `username`; Snapchat handles or profile URLs | | `maxResults` | integer 1–1000 | `25` | Caps videos scraped and billed | | `includeRawData` | boolean | `false` | Attach the raw per‑video metadata node | #### Trending volume note Snapchat's trending feed serves ~25 videos per request. To reach a higher `maxResults`, the actor re‑samples the feed across fresh proxy sessions and de‑duplicates by video ID, so a trending run may occasionally return slightly fewer than `maxResults` when Snapchat repeats videos. URL mode returns exactly one video per provided URL. ### Use via API / MCP The actor is exposed in the Apify MCP server as `apify--snapchat-spotlight-scraper`. Tool input is the same JSON above; the dataset is returned as structured rows an agent can read directly. ```bash apify call khadinakbar/snapchat-spotlight-scraper \ --input='{"mode":"trending","country":"US","maxResults":10}' ``` ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("khadinakbar/snapchat-spotlight-scraper").call( run_input={"mode": "trending", "country": "GB", "maxResults": 25} ) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["creatorUsername"], item["viewCount"], item["spotlightUrl"]) ``` ### How it works The actor reads Snapchat's public web Spotlight pages and parses the embedded `__NEXT_DATA__` application state — the same structured data the website itself renders. Trending and URL modes run over Apify proxies with session rotation for reliability and country targeting; `proxyType` defaults to `auto` (residential first, datacenter fallback). Datacenter is cheaper and avoids residential quota but works mainly for US — other countries generally need residential. Username mode is provider-backed and uses no proxy. No Snapchat account, cookies, or login are required. ### FAQ **Do I need a Snapchat login or cookies?** No. Only public Spotlight web data is read. **Can I get the actual video file?** Yes — `videoUrl` is the direct media URL. Respect Snapchat's terms and creator rights when downloading. **Why did trending return fewer than maxResults?** The live feed repeats videos across sessions; after de‑duplication you get the unique set. Lower `maxResults` or try another country for more variety. **Which countries are supported?** US, GB, CA, AU, IN, PK, FR, DE, ES, IT, BR, MX, NL, SA, AE, ID, PH, NG, ZA, JP — and any other ISO‑2 code works for the proxy. ### Legal & compliance This actor collects only publicly available data from Snapchat Spotlight web pages and does not access private content, accounts, or anything behind authentication. You are responsible for using the data in compliance with Snapchat's Terms of Service, applicable laws (including data‑protection and copyright law), and creator rights. Do not use scraped media or personal data in ways that violate those terms. This tool is provided for research, analytics, and lawful business use. # Actor input Schema ## `mode` (type: `string`): Use this to choose what to scrape. 'trending' pulls Snapchat's live Spotlight discovery feed for a country (no URLs needed). 'urls' scrapes the exact Spotlight URLs you provide. 'username' returns a creator's Spotlight videos by handle via the ScrapeCreators provider (needs the owner's API key, no residential proxy). Defaults to 'trending'. ## `spotlightUrls` (type: `array`): Use this when mode is 'urls' and you have specific Snapchat Spotlight links. Accepts full URLs like https://www.snapchat.com/spotlight/W7\_EDlXWTBiXAEEniNoMPwAAY... (one per line). Ignored when mode is 'trending'. Not for profile URLs such as snapchat.com/add/username. ## `usernames` (type: `array`): Use this when mode is 'username' and you want a creator's Spotlight videos. Accepts Snapchat handles or profile URLs like 'mrbeast' or https://www.snapchat.com/add/mrbeast (one per line). Requires the actor owner's SCRAPECREATORS\_API\_KEY. Ignored in trending and urls modes. ## `country` (type: `string`): Use this to pick which country's trending Spotlight feed to scrape; it also sets the residential proxy country. Accepts a two-letter ISO code such as US, GB, IN, PK, or SE (case-insensitive). Defaults to US. Only applies when mode is 'trending'. ## `proxyType` (type: `string`): Use this to choose the Apify proxy for trending and urls modes. 'auto' (default) tries residential first then falls back to datacenter on a proxy failure; 'residential' is most reliable and works for every country; 'datacenter' is cheaper and avoids residential quota but in practice works mainly for US - other countries usually need residential. Ignored in username mode. ## `maxResults` (type: `integer`): Use this to cap how many Spotlight videos are scraped and billed. Accepts 1 to 1000; default is 25, which matches one trending feed page. Lower values are best for testing cost and output shape. Trending mode re-samples the feed across sessions to reach this number. ## `includeRawData` (type: `boolean`): Use this only when debugging Snapchat payload drift or building a custom parser. Accepts true or false; default is false to keep MCP output compact. Raw data attaches the full per-video metadata node and can be large. Not needed for normal exports. ## Actor input object example ```json { "mode": "trending", "spotlightUrls": [], "usernames": [], "country": "US", "proxyType": "auto", "maxResults": 25, "includeRawData": false } ``` # Actor output Schema ## `results` (type: `string`): Spotlight video rows with creator, engagement counts, sound, AI caption, hashtags, thumbnail, and video download URLs, plus diagnostic rows. ## `runSummary` (type: `string`): Run diagnostics, counts, and cost telemetry. # 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 = { "mode": "trending", "spotlightUrls": [], "usernames": [], "country": "US", "proxyType": "auto", "maxResults": 25 }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/snapchat-spotlight-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 = { "mode": "trending", "spotlightUrls": [], "usernames": [], "country": "US", "proxyType": "auto", "maxResults": 25, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/snapchat-spotlight-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 '{ "mode": "trending", "spotlightUrls": [], "usernames": [], "country": "US", "proxyType": "auto", "maxResults": 25 }' | apify call khadinakbar/snapchat-spotlight-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/snapchat-spotlight-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Snapchat Spotlight Scraper", "description": "Scrape Snapchat Spotlight videos from the trending discovery feed by country or from specific Spotlight URLs. Returns views, shares, boosts, recommends, comments, creator, sound, AI caption, hashtags, and the video download URL. HTTP-only, no cookies. MCP-ready.", "version": "1.5", "x-build-id": "vsp8Kige5jDk9KnCQ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~snapchat-spotlight-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-snapchat-spotlight-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-spotlight-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-snapchat-spotlight-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-spotlight-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-snapchat-spotlight-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": [ "trending", "urls", "username" ], "type": "string", "description": "Use this to choose what to scrape. 'trending' pulls Snapchat's live Spotlight discovery feed for a country (no URLs needed). 'urls' scrapes the exact Spotlight URLs you provide. 'username' returns a creator's Spotlight videos by handle via the ScrapeCreators provider (needs the owner's API key, no residential proxy). Defaults to 'trending'.", "default": "trending" }, "spotlightUrls": { "title": "Spotlight URLs", "type": "array", "description": "Use this when mode is 'urls' and you have specific Snapchat Spotlight links. Accepts full URLs like https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAY... (one per line). Ignored when mode is 'trending'. Not for profile URLs such as snapchat.com/add/username.", "items": { "type": "string" } }, "usernames": { "title": "Creator Usernames", "type": "array", "description": "Use this when mode is 'username' and you want a creator's Spotlight videos. Accepts Snapchat handles or profile URLs like 'mrbeast' or https://www.snapchat.com/add/mrbeast (one per line). Requires the actor owner's SCRAPECREATORS_API_KEY. Ignored in trending and urls modes.", "items": { "type": "string" } }, "country": { "title": "Country (trending feed)", "type": "string", "description": "Use this to pick which country's trending Spotlight feed to scrape; it also sets the residential proxy country. Accepts a two-letter ISO code such as US, GB, IN, PK, or SE (case-insensitive). Defaults to US. Only applies when mode is 'trending'.", "default": "US" }, "proxyType": { "title": "Proxy Type (trending & urls)", "enum": [ "auto", "residential", "datacenter" ], "type": "string", "description": "Use this to choose the Apify proxy for trending and urls modes. 'auto' (default) tries residential first then falls back to datacenter on a proxy failure; 'residential' is most reliable and works for every country; 'datacenter' is cheaper and avoids residential quota but in practice works mainly for US - other countries usually need residential. Ignored in username mode.", "default": "auto" }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Use this to cap how many Spotlight videos are scraped and billed. Accepts 1 to 1000; default is 25, which matches one trending feed page. Lower values are best for testing cost and output shape. Trending mode re-samples the feed across sessions to reach this number.", "default": 25 }, "includeRawData": { "title": "Include Raw Data", "type": "boolean", "description": "Use this only when debugging Snapchat payload drift or building a custom parser. Accepts true or false; default is false to keep MCP output compact. Raw data attaches the full per-video metadata node and can be large. Not needed for normal exports.", "default": false } } }, "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 } } } } } } } } } } ```