# Snapchat Video Downloader (`agentx/snapchat-video-downloader`) Actor

Process one publicly accessible Snapchat Spotlight video for structured metadata and an optional stored video file.

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

## Pricing

Pay per event

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/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 Video Downloader processes one accessible Spotlight video into normalized metadata and can optionally store its available video file in Apify.

- Two public inputs cover one Spotlight URL and an optional download preference.
- Four quality values provide metadata-only, low, medium, and high processing modes.
- Successful output follows a 39-field Dataset contract with thumbnail-first review.
- Comment retrieval is not exposed; the reserved `comments` array is normally empty.

**[Run one Spotlight test](https://apify.com/agentx/snapchat-video-downloader)**

**[View the Apify API](https://apify.com/agentx/snapchat-video-downloader/api)**

Publish the Actor, replace the illustrative URL, and validate metadata before requesting a file.

### Why Choose This API

Snapchat Video Downloader offers a narrow one-URL workflow for public Spotlight media. It maps source information into stable cross-video fields rather than requiring a downstream application to understand extractor-specific names. Depending on the page, the record can include ID, title or description, thumbnail, author, duration, publication time, available counters, dimensions, and audio labels.

Metadata mode avoids media transfer. A download preference requests an available rendition and stores the file only when delivery succeeds. The source controls resolution and availability, so quality modes are preferences rather than guarantees.

The Actor is not a Snapchat account, Story, Map, Lens, Discover, search, profile, or comments scraper. This makes its release boundary testable: one accessible Spotlight video in, one normalized item out.

### Quick Start Guide

The documentation uses a URL-shaped placeholder because no durable public Spotlight sample was verified during the local audit:

```json
{
  "video_url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY3FzcW1ta3psAZ3oVmrkAZ3oVkadAAAAAQ",
  "video_quality": "metadata"
}
```

Replace `example` with a current Spotlight share identifier for content you may process. Open that URL in a private browser window, then submit it in metadata mode. Confirm that the returned ID, thumbnail, author, and title or description belong to the intended Spotlight item.

Only request a file after the metadata identity is correct. A successful run with an unrelated page or empty identity fields is not sufficient regression evidence. Multiple videos require separate runs.

### Input Parameters

| Parameter | Type | Required | Purpose |
|---|---|---:|---|
| `video_url` | string | Yes | One publicly accessible Snapchat Spotlight video URL. |
| `video_quality` | string | No | `metadata`, `low`, `medium`, or `high`; metadata skips file storage. |

The required URL has the illustrative prefill and matching example. The optional selector has no prefill or example, preserving whether the caller explicitly chose a mode; omission uses metadata in the runtime.

There are no Story, username, profile, query, date, market, language, credential, batch, or comment controls. Extra properties are rejected.

### Output Data Schema

The Dataset offers 39 possible fields:

| Area | Fields |
|---|---|
| Identity | `thumbnail`, `id`, `platform`, `title`, `description`, `duration`, `published_at` |
| Creator | `author`, `author_id`, `author_url` |
| Labels and counters | `categories`, `tags`, `view_count`, `like_count`, `shares_count`, `dislike_count`, `comment_count` |
| Media | `width`, `height`, `fps`, `audio_title`, `audio_artist`, `video` |
| Reserved and provenance | `comments`, `processed_at`, `processor` |

An abbreviated shape for the same placeholder is:

```json
{
  "id": "example",
  "platform": "SnapchatSpotlight",
  "title": "Example Spotlight video",
  "author": "Example creator",
  "thumbnail": "https://example.com/snapchat-thumbnail.jpg",
  "comments": [],
  "video": ""
}
```

This is a schema example, not live output. Fields may be null because Snapchat does not expose every cross-platform property. In metadata mode, `video` is empty. The public input does not request comments, so the reserved list is normally empty.

Source-dependent fields also present in every item:

| Field | Meaning |
|---|---|
| `source_url` | Canonical page URL of the item on its own platform |
| `media_type` | Kind of media the source reports, such as video or audio |
| `live_status` | Whether the item is a recording, currently live, or a finished stream |
| `availability` | Source visibility, such as public, unlisted, or needs\_auth |
| `age_limit` | Minimum viewer age the source enforces; zero means no restriction |
| `language` | Primary language of the item as reported by the source |
| `followers` | Follower or subscriber count of the author at processing time |
| `is_verified` | Whether the author's account carries a verified badge |
| `saves_count` | Times viewers saved the item, on sources that expose it |
| `file_ext` | Container extension of the selected media, such as mp4 or webm |
| `file_size` | Size of the selected media in bytes, exact or approximate |
| `subtitles` | Language codes of published subtitle tracks; auto-captions excluded |
| `chapters` | Chapter markers with title and start and end time in seconds |

### Integration Examples

The intended reference is `agentx/snapchat-video-downloader`.submit the same scenario through HTTP:

```bash
curl -X POST "https://api.apify.com/v2/acts/agentx~snapchat-video-downloader/runs?token=$APIFY_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"video_url":"https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY3FzcW1ta3psAZ3oVmrkAZ3oVkadAAAAAQ","video_quality":"metadata"}'
```

The matching hosted MCP setup is:

```json
{
  "mcpServers": {
    "apify-snapchat-video": {
      "url": "https://mcp.apify.com?tools=agentx/snapchat-video-downloader",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  },
  "exampleToolArguments": {
    "video_url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY3FzcW1ta3psAZ3oVmrkAZ3oVkadAAAAAQ",
    "video_quality": "metadata"
  }
}
```

Publication is required for tool discovery. Keep tokens private and follow the [Apify MCP documentation](https://docs.apify.com/integrations/mcp).

### Pricing & Cost Calculator

Local metadata declares these events, not a verified Store offer:

| Event | Billing unit | Local price |
|---|---|---:|
| `actor_usage` | Metered runtime, proxy, and storage usage | $0.00001 |
| `metadata` | One successfully processed metadata result | $0.09 |
| `download` | One successfully processed result with stored video | $0.20 |

The smallest metadata result declares $0.09 plus metered usage. A download result declares $0.20 plus metered usage instead.

### Use Cases & Applications

Media teams can attach a permitted Spotlight item and its thumbnail to a review record. Researchers can preserve available author, publication, duration, and counter fields for a cited public item. Developers can route the Dataset item through a webhook. AI teams can send an authorized stored file to a separate transcription or classification service.

Repeated metadata runs can observe the currently exposed values for one fixed URL, but the Actor does not calculate changes or deduplicate output. The caller must retain prior observations and treat missing values as unknown rather than zero.

For a review workflow, store the source share URL, returned media ID, thumbnail, author, run time, and requested mode together. Those values make it possible to distinguish a changed Spotlight item from a parser regression. If the creator removes the post later, the earlier Dataset item is historical evidence of that run, not proof that the source remains public.

For transcription, use metadata to confirm the asset before sending a downloaded file to another Actor. Keep the media-processing result separate from the Snapchat metadata record so retries, retention, and access decisions remain independently auditable.

### Limits & Troubleshooting

Spotlight availability can change because the creator removes media, Snapchat changes guest access, the share link expires, or a page becomes restricted. The Actor exposes no Snapchat login, cookie, device, or country selector.

If processing fails, replace the documentation placeholder with a real Spotlight share URL and open it privately. Confirm that it is a playable Spotlight item, then retry metadata mode. Do not use a profile, Story, or Discover URL.

If download mode produces no `video`, inspect logs and the key-value store, then retest metadata to isolate access from file delivery. Quality preferences cannot create absent renditions.

Before release, test a public Spotlight item, a removed item, a non-Spotlight Snapchat URL, and one download mode. Validate 26 output keys and an empty reserved comment list.

Capture a redacted evidence row for every case: URL type, run region, terminal status, detected extractor key, returned ID, thumbnail presence, requested quality, and file outcome. The placeholder should fail content extraction cleanly. The public case should return the intended identity. Out-of-scope Snapchat pages must not be counted as successful just because they render HTML.

After updating the downloader dependency, repeat the same matrix. Snapchat can change share-link routing independently of the Actor, so regression evidence must compare both media identity and contract shape rather than only exit status.

### FAQ

#### Does it download Snapchat Stories?

No. The documented surface is one public Spotlight video.

#### Can it process a profile or Discover page?

No. Those URL types are outside the input contract.

#### Does it retrieve comments?

No comment input exists; the reserved list is normally empty.

#### Is the example a real Spotlight item?

No. Replace the explicit placeholder with an authorized share URL.

#### Does high guarantee a specific resolution?

No. Available source renditions set the limit.

#### Why are output fields null?

The source did not expose those values. Null is not zero.

#### Can I schedule the Actor?

Yes, but each run repeats one URL and availability may change.

#### Why do Spotlight URLs look so long?

A Spotlight address embeds an opaque content token rather than a short numeric ID. Copy the whole address from the share sheet or the browser bar without trimming it; a shortened token resolves to the Spotlight feed instead of one item, and the run then ends without a Dataset item.

### Legal & Responsible Use

Use only content you are authorized to access, process, download, and retain. The user is responsible for platform terms, copyright, privacy, applicable law, and retention policy. The Actor must not be used to bypass access controls.

### Related Tools

- [Video Transcript](https://apify.com/agentx/video-transcript) turns authorized media speech into text.
- [Video Captions Downloader](https://apify.com/agentx/video-captions-downloader) retrieves available subtitle tracks.
- [Live Stream Transcript](https://apify.com/agentx/live-stream-transcript) serves live-audio transcription workflows.
- [All Video Scraper](https://apify.com/agentx/all-video-scraper) accepts supported URLs from multiple hosts.

### Support & Community

- [AgentX community](https://t.me/Apify_Actor)
- [Contact the AgentX team](https://t.me/AiAgentApi)
- [Apify Actor dashboard](https://apify.com/agentx/snapchat-video-downloader)
- [Apify API reference](https://apify.com/agentx/snapchat-video-downloader/api)
- [Apify MCP documentation](https://docs.apify.com/integrations/mcp)

Send the stable Actor ID, redacted real URL, input, and run ID with support requests.

**[Run one Spotlight test](https://apify.com/agentx/snapchat-video-downloader)**

**[View the Apify API](https://apify.com/agentx/snapchat-video-downloader/api)**

# Actor input Schema

## `video_url` (type: `string`):

Publicly accessible Snapchat Spotlight video URL to process.

## `video_quality` (type: `string`):

Preferred download quality, or metadata-only mode without a video file.

## Actor input object example

```json
{
  "video_url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY3FzcW1ta3psAZ3oVmrkAZ3oVkadAAAAAQ"
}
```

# Actor output Schema

## `results` (type: `string`):

All video details and optional download links with full engagement stats and comments

# 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 = {
    "video_url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY3FzcW1ta3psAZ3oVmrkAZ3oVkadAAAAAQ"
};

// Run the Actor and wait for it to finish
const run = await client.actor("agentx/snapchat-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 = { "video_url": "https://www.snapchat.com/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY3FzcW1ta3psAZ3oVmrkAZ3oVkadAAAAAQ" }

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

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/q5qkPabhaMeWxWVGa/builds/mpMoiv9dMdVxQ5H6N/openapi.json