# Snapchat Spotlight Video Downloader (`automation-lab/snapchat-spotlight-video-downloader`) Actor

Archive authorized public Snapchat Spotlight videos from supplied URLs. Export exact video metadata, source provenance and optional bounded MP4 files with SHA-256 hashes. No private Stories or discovery.

- **URL**: https://apify.com/automation-lab/snapchat-spotlight-video-downloader.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Social media, Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.40 / 1,000 spotlight video resolveds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Snapchat Spotlight Video Downloader

Archive rights-authorized public Spotlight clips from supplied URLs with this Snapchat Spotlight video downloader. Get exact video metadata, original source provenance and optional MP4 files stored with SHA-256 checksums. It resolves your video, not a recommended replacement.

### What it does

Supply canonical public Spotlight video URLs. Each unique successfully processed video becomes one dataset row. By default, its MP4 is also saved in the run's key-value store. Switch `saveVideos` off for metadata and temporary CDN links only.

This is a direct-link archival tool, not a search engine. It does not discover videos, scan profiles, download private Stories, accept login cookies or bypass account-only access. It cannot guarantee HD or availability after a source post is removed.

### Who it is for

- Creators archiving their own public clips.
- Agencies preserving client-authorized campaign assets.
- Media operations teams maintaining provenance manifests for approved content.

Public accessibility does not grant copyright or redistribution rights. Use only content you are authorized to process.

### Why use it?

An archival manifest needs more than a temporary download link. Stored-file mode records the file key, byte size and hash alongside the exact source ID and observation time. This makes downstream integrity checks and repeatable ingestion straightforward.

The resolver matches the requested ID against structured public source data. A page that contains other videos but lacks your requested video fails instead of silently substituting a popular clip.

### Getting started

1. Copy a public URL with `/spotlight/ID` or `/@username/spotlight/ID`.
2. Add it to **Spotlight video URLs**.
3. Keep **Store MP4 files** enabled if you need persistent bytes rather than a temporary source link.
4. Run the Actor.
5. Export dataset rows and copy MP4 records into your own archival storage as needed.

Example input:

```json
{
  "startUrls": [{"url":"https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYdXhoeXl1cGtwAZ_NZdDzAZ_NZdAHAAAAAw"}],
  "maxItems": 10,
  "saveVideos": true,
  "maxVideoSizeMb": 20
}
```

The example URL was anonymously accessible during testing. Public posts can later expire or be removed; replace it with an authorized current URL if needed.

### Inputs

| Field | Default | Behavior |
|---|---|---|
| `startUrls` | Required | 1–100 canonical HTTPS Snapchat Spotlight `{url}` objects |
| `maxItems` | 10 | Global maximum unique successful videos; integer 1–100 |
| `saveVideos` | true | Store MP4 bytes, or metadata-only when false |
| `maxVideoSizeMb` | 20 | Per-file limit, integer 1–20 MiB; one MiB is 1,048,576 bytes |

All inputs are validated before network work. Request-list entries support URL and optional `method=GET` only; custom payload, headers, userData and other methods are rejected. Zero/unlimited is unsupported. Repeated IDs count once, even if a username path differs. Source URL query strings are stripped. Processing follows input order and stops at the success limit. Unprocessed URLs beyond that limit are not resolved.

The size limit is still validated in metadata-only mode but no media download is performed. Files over the limit fail; they are not truncated. Share links such as `/t/...`, profile URLs and Story URLs are unsupported; copy the final canonical Spotlight URL instead.

### Output fields

| Group | Fields |
|---|---|
| Identity | `storyId`, `snapId`, `sourceUrl`, `provenance`, `observedAt` |
| Content | `title`, `caption`, `postedAt`, `thumbnailUrl`, `mediaUrl` |
| Creator | `creatorUsername`, `creatorName`, `creatorUrl` |
| Video | `durationMs`, `width`, `height` |
| Engagement | `viewCount`, `shareCount`, `commentCount` |
| Archive | `videoFileKey`, `videoFileUrl`, `videoSizeBytes`, `sha256` |

Missing source values remain null, not fabricated zeros. Source titles may be generic. Engagement is an observed source snapshot, not a historical series. Media/thumbnail URLs can expire; a media URL alone is not a permanent archive. Resolution and quality are exactly what Snapchat serves.

In metadata-only mode all archive fields are null. File URLs are storage record addresses, not promises of anonymous access: access follows your Apify storage permissions. Keep tokens out of exported manifests.

### Representative result

A tested public clip returned a 540×960 MP4 of 644,444 bytes, duration 8,130 ms. This abbreviated, anonymized record illustrates its structure; identifiers are examples:

```json
{
  "storyId": "EXAMPLE_SPOTLIGHT_ID",
  "snapId": "EXAMPLE_SPOTLIGHT_ID",
  "sourceUrl": "https://www.snapchat.com/spotlight/EXAMPLE_SPOTLIGHT_ID",
  "title": "Example creator caption",
  "creatorUsername": "examplecreator",
  "durationMs": 8130,
  "width": 540,
  "height": 960,
  "videoFileKey": "video-EXAMPLE_SPOTLIGHT_ID.mp4",
  "videoSizeBytes": 644444,
  "provenance": "snapchat-public-ssr"
}
```

The dataset contains the full fields listed above, including SHA-256 when a file is stored. Download MP4 files from the key-value store, not from the JSON dataset export.

### How much does it cost to archive Snapchat Spotlight videos?

The REPORT summary has no separate event charge.

The Actor uses pay-per-event pricing: one `start` event per valid run plus one `item` event per useful video result. Stored-file and metadata-only modes use the same item event; there is no additional download event. Invalid input fails before the start charge. Failed or duplicate videos do not incur an item charge.

The start fee is **$0.005 per run**. Per-video item prices are:

| Spend tier | Price per video |
|---|---:|
| FREE | $0.0046 |
| BRONZE | $0.004 |
| SILVER | $0.00312 |
| GOLD | $0.0024 |
| PLATINUM | $0.0024 |
| DIAMOND | $0.0024 |

At BRONZE, 1 video costs an estimated $0.009, 10 videos $0.045, and 100 videos $0.405, including the start fee. Consult the live Pricing tab for current tier prices before running. Higher spend tiers depend on qualifying aggregate monthly Store spend under Apify rules, not this Actor's batch size. Example costs are estimates, not guaranteed invoices. Your own storage/export costs can be separate. Runtime, source availability and configured billing limits can affect completion.

### Limits and failure behavior

Requests are sequential and transient network/429/5xx failures have at most two retries. No residential proxy, paid API, login service or browser fallback is enabled. An MP4 must be served from an allowed Snapchat CDN host and pass the MP4 header check. Every redirect is checked before requesting its destination.

HTML downloads are capped at 8 MiB; MP4s are capped at the chosen file limit. At most 100 supplied unique videos can be processed in one run. These are processing bounds, not claims of unlimited upstream coverage.

If a requested target fails, successful earlier results remain available, but the run is marked failed with partial output. Inspect the `REPORT` key for counts and query-free failed source URLs. Do not treat partial rows as a complete batch.

Budget exhaustion stops further output; inspect actual results and run charges.

### Integrations

Export the default dataset to JSON/CSV for a rights ledger or asset manifest. Fetch each `videoFileUrl` with authorized Apify storage access and stream the MP4 into your own storage outside model context. Verify the bytes against `sha256` before accepting them into your archive.

Apify schedules can re-run an explicitly maintained list of URLs. Scheduling does not discover new posts or guarantee continued access. Webhooks can trigger ingestion after success; route failed runs to partial-result review rather than silently ingesting an incomplete batch.

### API: cURL

Keep the token in an environment variable:

```bash
curl -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  'https://api.apify.com/v2/acts/automation-lab~snapchat-spotlight-video-downloader/runs' \
  -d '{"startUrls":[{"url":"https://www.snapchat.com/spotlight/EXAMPLE_SPOTLIGHT_ID"}],"saveVideos":true}'
```

This returns run metadata. Retain the run ID, wait for terminal status, and then read its `defaultDatasetId` and `defaultKeyValueStoreId`. IDs are not result rows.

### API: JavaScript

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({token: process.env.APIFY_TOKEN});
const run = await client.actor('automation-lab/snapchat-spotlight-video-downloader').call({
  startUrls: [{url: process.env.SPOTLIGHT_URL}], saveVideos: true
});
if (run.status !== 'SUCCEEDED') throw new Error('Incomplete batch: ' + run.id);
const page = await client.dataset(run.defaultDatasetId).listItems({limit: 20});
console.log(page.items);
```

### API: Python

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/snapchat-spotlight-video-downloader').call(
    run_input={'startUrls': [{'url': os.environ['SPOTLIGHT_URL']}], 'saveVideos': True}
)
if run['status'] != 'SUCCEEDED':
    raise RuntimeError('Incomplete batch: ' + run['id'])
print(client.dataset(run['defaultDatasetId']).list_items(limit=20).items)
```

### MCP setup

Use the scoped hosted endpoint. Claude Code:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=automation-lab/snapchat-spotlight-video-downloader"
```

Claude Desktop and Cursor MCP JSON configuration (configure authentication through the client's protected flow):

```json
{"mcpServers":{"apify":{"url":"https://mcp.apify.com?tools=automation-lab/snapchat-spotlight-video-downloader"}}}
```

VS Code MCP configuration:

```json
{"servers":{"apify":{"type":"http","url":"https://mcp.apify.com?tools=automation-lab/snapchat-spotlight-video-downloader"}}}
```

Example prompt: “Resolve this authorized Spotlight URL, store its MP4, and return the source ID, file key and hash.” Another: “Resolve these supplied URLs in metadata-only mode, at most five video results; do not discover other posts.”

Discover actual tool names and input schemas with scoped `tools/list`. Actor selection also exposes run/dataset/key-value-store/abort helpers; it does not expose exactly one tool. Discovery is read-only and is not permission to execute or abort.

After an authorized invocation, start once and follow that same run ID. `call-actor` waits at most 45 seconds (`waitSecs`, default 30). For nonterminal status, check the same run with bounded backoff, for example 2/4/8 seconds capped at 10, and a 120-second total deadline. Set client timeout above server wait plus transport margin. Recover the known run after client timeout; never restart just to poll. If the ID is unknown, report uncertainty. At deadline, report pending with the run ID.

On success, read bounded results: pages of 20 source rows, at most 100 rows and 64 KiB serialized UTF-8 content admitted to model context, whichever comes first. Enforce the byte ceiling host-side and disclose omitted/oversized rows; if the client cannot intercept responses, do not claim a hard byte guarantee. Track source offsets, return the continuation offset, and disclose truncation. Keep full files and exports outside model context. Terminal failures mean partial data, not a complete result. No universal token-savings claim is made.

### Legality and data handling

This independent tool is not affiliated with or endorsed by Snapchat or Snap Inc. Source names identify compatibility only. Apify standard terms apply. Respect source terms, privacy law, copyright and the rights of depicted people. Avoid sensitive or unauthorized content.

No AI model is called at runtime. The Actor reads existing public source metadata without generating titles or descriptions. No user cookies, credentials or private accounts are requested. It does not include source-provided generated SEO descriptions as its own output.

Public creator names/usernames, captions, engagement and media are intentionally present in result storage. Network processing is ephemeral; no cross-run cache or shared named dataset is used. Apify stores input, logs, datasets and files under its platform retention settings; copy needed files and delete runs/stores according to your retention policy. There is no additional long-term content backup operated by this Actor.

Failed operations send sanitized diagnostic input, exceptions and actor/build/run IDs to our private GlitchTip service for repair; secret fields and URL queries are removed and reports are retained for 30 days. Diagnostics are not a media archive. Do not put credentials in inputs. Logs use counts and IDs, not captions, source media bytes or signed URLs.

### Troubleshooting and FAQ

**Why is my URL rejected?** Use a canonical Spotlight video URL, not a short share link, Story or profile URL. Only HTTPS `snapchat.com` and `www.snapchat.com` are accepted.

**Why did a visible page fail?** A page may show recommendations when the exact post is unavailable. The Actor refuses to replace your requested ID. The post may also have been removed or become unavailable anonymously.

**Why is there no MP4?** Set `saveVideos=true`, check the size cap and inspect `REPORT`. Metadata-only results intentionally have null archive fields.

**Is it HD or watermark-free?** No such guarantee. The file is exactly the permitted public MP4 Snapchat returns, without enhancement or watermark removal.

**How do I report a bug?** Open an Apify Store issue with the run link and a public example URL you are authorized to share. Do not post secrets or private content. Include whether file or metadata-only mode failed.

### Related Actors

Use [Snapchat Spotlight Discovery Scraper](https://apify.com/automation-lab/snapchat-spotlight-discovery-scraper) for public discovery metadata, rather than supplied-link file archival. Use [Snapchat Public Profile Metadata](https://apify.com/automation-lab/snapchat-public-profile-metadata) for public profile identity research. These are separate jobs and do not imply private Story access.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/snapchat-spotlight-video-downloader/changelog.md

# Actor input Schema

## `startUrls` (type: `array`):

Supply 1–100 HTTPS snapchat.com /spotlight/ID or /@username/spotlight/ID URLs. Only URL and optional method=GET are supported; custom payload, headers, userData and other methods are rejected. All entries are validated before work. Query strings are stripped. Duplicates by ID produce one row. No /t/ share links, Stories or profile discovery.

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

Global maximum unique successful videos per run, in supplied order; default 10, range 1–100. Zero is invalid. Duplicate IDs do not consume the limit. Stops fetching when reached; remaining URLs are not processed.

## `saveVideos` (type: `boolean`):

Default true: download and validate each MP4 into this run's key-value store before emitting its metadata. False returns metadata and temporary source media URLs without files. Failed downloads do not emit or charge an item. Same item price in either mode.

## `maxVideoSizeMb` (type: `integer`):

Per-video byte limit in MiB (1,048,576 bytes), default and maximum 20, minimum 1. Enforced during download even without Content-Length. Oversized videos fail, not truncate. Ignored for downloading when saveVideos=false, but still validated.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYdXhoeXl1cGtwAZ_NZdDzAZ_NZdAHAAAAAw"
    }
  ],
  "maxItems": 10,
  "saveVideos": true,
  "maxVideoSizeMb": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

Exact supplied-video metadata and archive provenance.

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

Stored MP4 records and REPORT processing summary.

# 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 = {
    "startUrls": [
        {
            "url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYdXhoeXl1cGtwAZ_NZdDzAZ_NZdAHAAAAAw"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/snapchat-spotlight-video-downloader").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 = { "startUrls": [{ "url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYdXhoeXl1cGtwAZ_NZdDzAZ_NZdAHAAAAAw" }] }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/snapchat-spotlight-video-downloader").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 '{
  "startUrls": [
    {
      "url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYdXhoeXl1cGtwAZ_NZdDzAZ_NZdAHAAAAAw"
    }
  ]
}' |
apify call automation-lab/snapchat-spotlight-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/snapchat-spotlight-video-downloader"
        }
    }
}
```

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/3V6uK9vjeSItmCHFj/builds/qtegsLMn6Ji8scJhR/openapi.json