# Snapchat Story Scraper (`codenest/snapchat-story-scraper`) Actor

Extract unlimited Snapchat Stories at rocket speed with rich metadata! 📸 Filters by year & story limit. Output includes direct media URLs, timestamps, story titles, and snap counts. Perfect for content archiving & trend analysis! 🚀Snapchat Story Scraper🚀.

- **URL**: https://apify.com/codenest/snapchat-story-scraper.md
- **Developed by:** [CodeNest](https://apify.com/codenest) (community)
- **Categories:** Social media, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.
You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors

## 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 Story Scraper 📸 - Professional Story & Media Downloader

**Effortlessly scrape and download Snapchat Stories with our powerful Snapchat Story Scraper! This enterprise-grade Apify actor enables you to extract Stories content with comprehensive metadata, direct media URLs, and intelligent filtering options.**

---

### 🎯 Overview
Need to archive Snapchat content or analyze Stories trends? This **Snapchat Story Scraper** delivers:
- **Multi-format extraction**: Videos & images with preview thumbnails
- **Temporal filtering**: Scrape by year for targeted data collection
- **Batch processing**: Handle multiple usernames simultaneously
- **Rich metadata**: Creation timestamps, story titles, media types
- **Direct CDN access**: High-quality media URLs

Perfect for social media analysts 📊, content researchers 🔬, and brand managers 🏢!

### ⚡ Core Capabilities/Key Features

#### 🔍 Smart Filtering Options
- **Year Filtering**: Target specific time periods (e.g., 2024 content only)
- **Story Limiting**: Control output volume with adjustable limits
- **Batch Usernames**: Process multiple accounts in single run

#### 📱 Media Extraction
- **Dual URLs**: Preview + original media links
- **Format Detection**: Auto-identify video vs. image content
- **Thumbnails**: High-quality preview images
- **Bulk Mode**: Process multiple Stories per account

#### 📊 Metadata Mastery
- **Precise Timestamps**: ISO-formatted creation dates
- **Story Organization**: Grouped snap lists with titles
- **Media Counts**: Video/Image totals
- **Indexed Snaps**: Sequential ordering for analysis

#### 🛠 Advanced Tech
- **Direct CDN Links**: No intermediate processing
- **Structured Output**: Clean JSON organization
- **Error Handling**: Graceful failure recovery
- **Scalable Architecture**: Handle large datasets

---

### ⚙️ Input Configuration
Configure your **Snapchat Story Scraper** with these simple JSON parameters:

```json
{
  "filterByYear": 2024,
  "storyLimit": 10,
  "usernames": [
    "fcbarcelona"
  ]
}
````

#### 📋 Input Specifications

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filterByYear` | Number | No | Filter Stories by specific year (e.g., 2024) |
| `storyLimit` | Number | No | Maximum number of Stories to fetch per user |
| `usernames` | Array | Yes | Snapchat usernames to scrape |

***

### 📤 Output Structure

Your **Snapchat Story Scraper** delivers comprehensive JSON output:

```json
[
  {
    "username": "fcbarcelona",
    "success": true,
    "stories": [
      {
        "snapList": [
          {
            "snapIndex": 0,
            "createTime": "2024-10-16T19:01:13.000Z",
            "mediaPreviewUrl": "https://cf-st.sc-cdn.net/...",
            "mediaUrl": "https://cf-st.sc-cdn.net/...",
            "mediaType": "video"
          }
        ],
        "storyTitle": "🌕🔵🔴",
        "thumbnailUrl": "https://cf-st.sc-cdn.net/...",
        "highlightId": "",
        "username": "fcbarcelona"
      }
    ],
    "totalStories": 2,
    "totalSnaps": 24,
    "error": null,
    "videoCount": 19,
    "imageCount": 5
  }
]
```

#### 📊 Output Field Documentation

**Account Summary**
| Field | Description |
|-------|-------------|
| `username` | Scraped Snapchat username |
| `success` | Boolean indicating scrape success |
| `totalStories` | Number of Stories retrieved |
| `totalSnaps` | Total media items across all Stories |
| `videoCount` | Number of video snaps extracted |
| `imageCount` | Number of image snaps extracted |
| `error` | Error message (null if successful) |

**Story-Level Data**
| Field | Description |
|-------|-------------|
| `storyTitle` | Title/description of the Story |
| `thumbnailUrl` | Preview image URL for the Story |
| `highlightId` | Story highlight identifier |

**Snap-Level Details**
| Field | Description |
|-------|-------------|
| `snapIndex` | Sequential position within Story |
| `createTime` | ISO 8601 creation timestamp |
| `mediaPreviewUrl` | Preview/thumbnail URL |
| `mediaUrl` | Original media download URL |
| `mediaType` | Content type (video/image) |

***

### 🎨 Media Quality & Types

The **Snapchat Story Scraper** preserves original media quality:

#### 📹 Video Content

- **Original resolution** preservation
- **Direct CDN access** for maximum quality
- **Multiple bitrate options** (when available)
- **Streaming-optimized** formats

#### 🖼️ Image Content

- **Full-resolution** downloads
- **Preview thumbnails** included
- **Original aspect ratios** maintained
- **No compression** artifacts

#### 🔄 Format Support

- **Video formats**: Various Snapchat-optimized codecs
- **Image formats**: High-quality JPEG/WebP
- **Metadata**: Complete technical specifications
- **URL structure**: Direct access to Snapchat CDN

***

### 💡 Technical Features

#### 🔧 Advanced Extraction

- **Direct API integration** for reliable scraping
- **Media type detection** with fallback options
- **URL validation** and normalization
- **Batch processing** optimization

#### 📈 Metadata Processing

- **ISO timestamp** standardization
- **Media indexing** for sequential playback
- **Story grouping** logical organization
- **Count aggregation** for analytics

#### 🛡️ Reliability Features

- **Error resilience** with detailed reporting
- **Rate limiting** awareness
- **Session management** for consistent access
- **Data validation** at multiple levels

***

### 🎯 Use Cases

- **Brand Managers** – Monitor competitor Stories 📈
- **Content Creators** – Archive and repurpose content 🎬
- **Researchers** – Analyze social media trends 📊
- **Marketers** – Track campaign performance 🎯
- **Developers** – Build Snapchat-integrated apps 📱
- **Analysts** – Study engagement patterns 🔍

***

#### 🤔 Why Choose Our Snapchat Story Scraper?

- **Reliable Performance**: Stable extraction with minimal failures
- **User-Friendly Configuration**: Simple JSON input structure
- **Comprehensive Data**: Complete metadata and media URLs
- **Time-Saving Filters**: Year-based filtering for targeted scraping
- **Regular Maintenance**: Updated for Snapchat API changes
- **Enterprise-Ready**: Scalable for large-volume operations

***

#### ⚠️ Limitations

- Only works with **public Snapchat accounts**
- Subject to Snapchat's **rate limits** and **API restrictions**
- Requires **valid usernames** (case-sensitive)
- Media URLs may have **expiration times**
- **Private accounts** cannot be scraped

### 🔗🛠 Related Actors (Social Media Suite)

Explore our comprehensive social media scraping suite:

#### 📸 Instagram Tools:

- [Instagram Reels Downloader](https://apify.com/codenest/instagram-reels-downloader)

#### 🎥 YouTube Scrapers:

- [YouTube Video Scraper](https://apify.com/codenest/youtube-video-scraper)
- [YouTube Video Transcript Scraper](https://apify.com/codenest/youtube-video-transcript-scraper)

#### 📘 Facebook Tools:

- [Facebook Reels Downloader](https://apify.com/codenest/facebook-reels-downloader)

***

### 📧 Need Customization?

Want **additional filters, enhanced metadata, or custom integrations**?

✉ Email **<codenest2.0@gmail.com>** for tailored solutions!

***

*Note: This **Snapchat Story Scraper** is designed for ethical use in compliance with Snapchat's Terms of Service. Always respect copyright and privacy laws when using scraped content.*

# Actor input Schema

## `usernames` (type: `array`):

A list of Snapchat usernames or profile URLs (e.g., 'fcbarcelona' or 'https://www.snapchat.com/add/fcbarcelona')

## `storyLimit` (type: `integer`):

Maximum number of story highlights to return. Set to 0 for all stories.

## `filterByYear` (type: `integer`):

Only include snaps from a specific year (e.g., 2024). Leave empty for all years.

## `yearRangeStart` (type: `integer`):

Start year for filtering (inclusive). Use with 'Year Range End' for a range filter.

## `yearRangeEnd` (type: `integer`):

End year for filtering (inclusive). Use with 'Year Range Start' for a range filter.

## `proxy` (type: `object`):

Proxy settings for the actor. Default uses US Residential proxies.

## Actor input object example

```json
{
  "usernames": [
    "fcbarcelona"
  ],
  "storyLimit": 0,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# 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 = {
    "usernames": [
        "fcbarcelona"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("codenest/snapchat-story-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 = { "usernames": ["fcbarcelona"] }

# Run the Actor and wait for it to finish
run = client.actor("codenest/snapchat-story-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 '{
  "usernames": [
    "fcbarcelona"
  ]
}' |
apify call codenest/snapchat-story-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Snapchat Story Scraper",
        "description": "Extract unlimited Snapchat Stories at rocket speed with rich metadata! 📸 Filters by year & story limit. Output includes direct media URLs, timestamps, story titles, and snap counts. Perfect for content archiving & trend analysis! 🚀Snapchat Story Scraper🚀.",
        "version": "0.0",
        "x-build-id": "zjxT9wRdCLquD2b9f"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/codenest~snapchat-story-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-codenest-snapchat-story-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/codenest~snapchat-story-scraper/runs": {
            "post": {
                "operationId": "runs-sync-codenest-snapchat-story-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/codenest~snapchat-story-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-codenest-snapchat-story-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",
                "required": [
                    "usernames"
                ],
                "properties": {
                    "usernames": {
                        "title": "Snapchat Usernames",
                        "type": "array",
                        "description": "A list of Snapchat usernames or profile URLs (e.g., 'fcbarcelona' or 'https://www.snapchat.com/add/fcbarcelona')",
                        "items": {
                            "type": "string"
                        }
                    },
                    "storyLimit": {
                        "title": "Story Limit",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum number of story highlights to return. Set to 0 for all stories.",
                        "default": 0
                    },
                    "filterByYear": {
                        "title": "Filter by Year",
                        "type": "integer",
                        "description": "Only include snaps from a specific year (e.g., 2024). Leave empty for all years."
                    },
                    "yearRangeStart": {
                        "title": "Year Range Start",
                        "type": "integer",
                        "description": "Start year for filtering (inclusive). Use with 'Year Range End' for a range filter."
                    },
                    "yearRangeEnd": {
                        "title": "Year Range End",
                        "type": "integer",
                        "description": "End year for filtering (inclusive). Use with 'Year Range Start' for a range filter."
                    },
                    "proxy": {
                        "title": "Proxy Configuration",
                        "type": "object",
                        "description": "Proxy settings for the actor. Default uses US Residential proxies.",
                        "default": {
                            "useApifyProxy": true,
                            "apifyProxyGroups": [
                                "RESIDENTIAL"
                            ],
                            "apifyProxyCountry": "US"
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
