# Facebook Story Downloader ✨ (`scrapearchitect/facebook-story-downloader`) Actor

🔬Input any public Facebook Story URL and receive permanent, never-expiring Apify CDN links for every story inside it: 🎬 HD Video (MP4), 📹 SD Video (MP4), 🎵 MP3 Audio & 🖼️ Photo. Enable 🔬 Media Metadata to get codec, resolution, bitrate & frame rate per file. 📸 Facebook Story Downloader 🔬

- **URL**: https://apify.com/scrapearchitect/facebook-story-downloader.md
- **Developed by:** [Scrape Architect](https://apify.com/scrapearchitect) (community)
- **Categories:** Social media, Videos, Automation
- **Stats:** 6 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.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 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

## 📸 Facebook Story Downloader & Media Metadata Scraper

> The most complete **Facebook Story Downloader** on the Apify platform — download every individual story from any public Facebook Story URL with **permanent, never-expiring download links** for HD Video, SD Video, MP3 Audio, and Photo. Optionally unlock deep container-level media metadata for every story file.

***

### 🚀 What This Facebook Story Downloader Does

This **Facebook Story Downloader** takes any public Facebook Story URL and automatically delivers:

- 🎬 **Video HD** — Highest quality video version, optimized for instant streaming
- 📹 **Video SD** — Standard quality version with a smaller file footprint
- 🎵 **Audio MP3** — Audio track properly converted to MP3 format at 128 kbps — not an mp4 container disguised as audio
- 🖼️ **Photo** — Full-resolution story photo hosted permanently on Apify CDN
- 🖼️ **Thumbnail** — Story cover image uploaded permanently alongside all results
- 🔬 **Media Metadata** *(optional toggle)* — Deep codec-level inspection of every file: codec name, resolution, frame rate, bitrate, duration, sample rate, audio channels, pixel format, and more

All download links produced by this **Facebook Story Downloader** are hosted permanently on the **Apify Key-Value Store** — unlike raw Facebook CDN links that expire within hours, these links **never expire** and can be shared, embedded, or archived indefinitely.

***

### ⚡ Key Features of This Facebook Story Downloader

| Feature | Details |
|---------|---------|
| 🔗 **Permanent Download Links** | All files uploaded to Apify CDN — links never expire |
| 📦 **Multi-Story Support** | Each Facebook Story URL can contain multiple individual stories — all are automatically detected and downloaded |
| 🎵 **True MP3 Conversion** | Audio is re-encoded to a proper MP3 file, not just renamed — plays correctly in every media player and browser |
| 🎬 **Web-Optimized Video** | Videos are processed with faststart optimization for instant browser playback |
| 🔬 **Deep Media Analysis** | Optional FFprobe-powered metadata extraction — codec, resolution, frame rate, bitrate, duration, and more |
| 🛡️ **Cloudflare Bypass** | This Facebook Story Downloader uses advanced browser fingerprint impersonation to reliably pass Cloudflare protection |
| 🔢 **Batch Processing** | Supply multiple Story URLs in a single run — each is processed independently |
| 🧹 **Clean Output** | Structured JSON with every story numbered and every format clearly labeled |
| 🔒 **No Credentials Exposed** | Internal implementation details, module names, and engine layers are never included in logs or output |

***

### 📥 Input Parameters

The **Facebook Story Downloader** accepts the following input parameters:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `facebook_urls` | Array of URL objects | ✅ Yes | — | List of public Facebook Story URLs. Each URL may contain multiple individual stories. |
| `include_media_metadata` | Boolean | ❌ No | `false` | When `true`, runs deep container-level analysis on every downloaded file and includes the metadata in the output. |

#### Example Input

```json
{
  "facebook_urls": [
    {
      "url": "https://www.facebook.com/stories/122093654840067130/UzpfSVNDOjI2NjM1MDI5MzQwMDYwNzQ="
    }
  ],
  "include_media_metadata": false
}
```

***

### 📤 Output Structure

Every URL processed by this **Facebook Story Downloader** produces one structured result item pushed to the Apify dataset.

***

#### 📋 Top-Level Fields

| Field | Type | Description |
|-------|------|-------------|
| `original_url` | String | The Facebook Story URL that was submitted for processing |
| `title` | String | Story title extracted from the source (e.g., `[Facebook Story] [4] [World Of Animals]`) |
| `source` | String | Media source identifier — typically `FB-Story` |
| `thumbnail` | String | Permanent Apify CDN URL for the story cover thumbnail (JPEG) |
| `total_stories` | Integer | Number of individual stories found and processed within the URL |
| `stories` | Array | Array of individual story result objects — see below |

***

#### 🎬 Per-Story Fields

Each object inside the `stories` array contains:

| Field | Type | Description |
|-------|------|-------------|
| `story_number` | Integer | Sequential index of this story (1, 2, 3, ...) |
| `video_hd` | String | Permanent CDN URL — highest quality MP4 video with faststart optimization |
| `video_sd` | String | Permanent CDN URL — standard quality MP4 video with faststart optimization |
| `audio_mp3` | String | Permanent CDN URL — MP3 audio file (128 kbps, properly converted from source) |
| `photo` | String | Permanent CDN URL — story photo as a JPEG image |
| `*_error` | String | Present only if a specific format failed to download or upload — contains the error description without exposing internal details |

***

#### 🔬 Media Metadata Fields (when `include_media_metadata` is `true`)

When the metadata toggle is enabled, each story also includes additional fields alongside its download links.

##### `video_hd_metadata` and `video_sd_metadata`

| Field | Description |
|-------|-------------|
| `codec_name` | Video codec identifier (e.g., `h264`, `vp9`, `av1`) |
| `codec_long_name` | Human-readable codec name (e.g., `H.264 / AVC / MPEG-4 AVC / part 10`) |
| `profile` | Codec encoding profile (e.g., `High`, `Baseline`, `Main`) |
| `width` | Video width in pixels |
| `height` | Video height in pixels |
| `display_aspect_ratio` | Aspect ratio string (e.g., `9:16` for vertical, `16:9` for landscape) |
| `pix_fmt` | Pixel format (e.g., `yuv420p`) |
| `r_frame_rate` | Frame rate as a fraction (e.g., `30/1`) |
| `avg_frame_rate` | Average frame rate over the full video |
| `bit_rate` | Video bitrate in bits per second |
| `max_bit_rate` | Maximum bitrate if variable (VBR) |
| `nb_frames` | Total number of video frames |
| `container_format_name` | Container format (e.g., `mov,mp4,m4a,3gp`) |
| `container_duration` | Total duration in seconds (e.g., `12.533`) |
| `container_size` | Total file size in bytes |
| `container_bit_rate` | Overall container bitrate in bits per second |

##### `audio_metadata`

| Field | Description |
|-------|-------------|
| `codec_name` | Audio codec (always `mp3` after conversion) |
| `codec_long_name` | Full codec name (e.g., `MP3 (MPEG audio layer 3)`) |
| `profile` | Codec profile if applicable |
| `sample_rate` | Audio sample rate in Hz (e.g., `44100`) |
| `channels` | Number of audio channels (e.g., `2` for stereo, `1` for mono) |
| `channel_layout` | Channel layout string (e.g., `stereo`) |
| `bit_rate` | Audio bitrate in bits per second (128000 for 128 kbps) |
| `container_duration` | Duration in seconds |
| `container_size` | File size in bytes |

##### `photo_metadata`

| Field | Description |
|-------|-------------|
| `file_size_bytes` | JPEG file size in bytes |
| `format` | Always `JPEG` |

***

### 📊 Example Output

The following examples show real output produced by the **Facebook Story Downloader**.

#### Without Metadata (`include_media_metadata: false`)

```json
{
  "original_url": "https://www.facebook.com/stories/122093654840067130/UzpfSVNDOjI2NjM1MDI5MzQwMDYwNzQ=",
  "title": "[Facebook Story] [4] [World Of Animals]",
  "source": "FB-Story",
  "thumbnail": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/thumb_abc123.jpg?disableContentDisposition=true",
  "total_stories": 4,
  "stories": [
    {
      "story_number": 1,
      "video_hd": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/video_hd_abc123.mp4?disableContentDisposition=true",
      "video_sd": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/video_sd_abc123.mp4?disableContentDisposition=true",
      "audio_mp3": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/audio_abc123.mp3?disableContentDisposition=true",
      "photo": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/photo_abc123.jpg?disableContentDisposition=true"
    },
    {
      "story_number": 2,
      "video_hd": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/video_hd_def456.mp4?disableContentDisposition=true",
      "video_sd": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/video_sd_def456.mp4?disableContentDisposition=true",
      "audio_mp3": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/audio_def456.mp3?disableContentDisposition=true",
      "photo": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/photo_def456.jpg?disableContentDisposition=true"
    }
  ]
}
```

#### With Metadata (`include_media_metadata: true`)

```json
{
  "original_url": "https://www.facebook.com/stories/122093654840067130/...",
  "title": "[Facebook Story] [4] [World Of Animals]",
  "source": "FB-Story",
  "thumbnail": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/thumb_abc123.jpg?disableContentDisposition=true",
  "total_stories": 4,
  "stories": [
    {
      "story_number": 1,
      "video_hd": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/video_hd_abc123.mp4?disableContentDisposition=true",
      "video_hd_metadata": {
        "codec_name": "h264",
        "codec_long_name": "H.264 / AVC / MPEG-4 AVC / part 10",
        "profile": "High",
        "width": 720,
        "height": 1280,
        "display_aspect_ratio": "9:16",
        "pix_fmt": "yuv420p",
        "r_frame_rate": "30/1",
        "avg_frame_rate": "30/1",
        "bit_rate": "2465223",
        "nb_frames": "375",
        "container_format_name": "mov,mp4,m4a,3gp,3g2,mj2",
        "container_duration": "12.533333",
        "container_size": "3861295",
        "container_bit_rate": "2466272"
      },
      "video_sd": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/video_sd_abc123.mp4?disableContentDisposition=true",
      "video_sd_metadata": {
        "codec_name": "h264",
        "profile": "Baseline",
        "width": 360,
        "height": 640,
        "display_aspect_ratio": "9:16",
        "r_frame_rate": "30/1",
        "bit_rate": "666456",
        "container_duration": "12.533333",
        "container_size": "1044812"
      },
      "audio_mp3": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/audio_abc123.mp3?disableContentDisposition=true",
      "audio_metadata": {
        "codec_name": "mp3",
        "codec_long_name": "MP3 (MPEG audio layer 3)",
        "sample_rate": "44100",
        "channels": 2,
        "channel_layout": "stereo",
        "bit_rate": "128000",
        "container_duration": "12.503484",
        "container_size": "200058"
      },
      "photo": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/photo_abc123.jpg?disableContentDisposition=true",
      "photo_metadata": {
        "file_size_bytes": 89432,
        "format": "JPEG"
      }
    }
  ]
}
```

***

### 🎯 Use Cases for the Facebook Story Downloader

- **Content Archiving** — Use this **Facebook Story Downloader** to preserve public Facebook Stories before they disappear after 24 hours, with permanent CDN links that last forever
- **Media Research** — Analyse story content, quality, and format across multiple Facebook pages or profiles
- **Social Media Monitoring** — Track and archive story media for brand monitoring, competitive intelligence, or trend analysis
- **Content Repurposing** — Download stories for republishing across other platforms, newsletters, or presentations
- **Quality Auditing** — Enable the metadata toggle to audit resolution, codec, bitrate, and aspect ratio at scale
- **Digital Asset Management** — Build a permanent media library of Facebook story content with categorised download links
- **Investigative Research** — Use this **Facebook Story Downloader** to archive public stories as evidence with timestamped, immutable CDN links

***

### ⚙️ Technical Notes

The following technical details apply to this **Facebook Story Downloader**:

- Only **public** Facebook Stories can be downloaded. Private, friends-only, or deleted stories are not accessible.
- Facebook Story links expire after the standard **24-hour window** — run this actor while stories are still live to get the download links before they disappear.
- Audio is **re-encoded** to proper MP3 format — the source audio arrives inside a video container, and this actor extracts and converts it to a standalone MP3 file that plays correctly in all media players and browsers.
- Videos are processed with **MP4 faststart** (moov atom moved to the front), enabling instant in-browser playback and progressive loading without downloading the entire file first.
- If a single format (e.g., HD video for one story) fails to process, the actor logs the error and continues — other formats and other stories are not affected.
- Each Facebook Story URL may contain **multiple individual stories** (typically 1–9). This **Facebook Story Downloader** detects and downloads all of them in a single run.
- All temporary files are cleaned up from the container after upload — the actor leaves no orphaned files.

***

### ❓ Troubleshooting

Use the table below to diagnose common issues with the **Facebook Story Downloader**:

| Symptom | Likely Cause | Solution |
|---------|-------------|---------|
| `CSRF token not found` | Temporary page structure change | Retry the run — usually auto-resolves |
| `API request failed: 403` | Story URL is private or the story has expired | Verify the story is public and still active |
| `0 stories found` | URL format not recognised | Provide the full story URL from Facebook — the **Facebook Story Downloader** requires the complete unshortened link |
| `KV upload failed` | File too large for available memory | Increase memory allocation in actor settings |
| `Thumbnail upload failed` | CDN URL expired before download | Actor falls back to including the original thumbnail URL |
| `video_hd_error` in output | Format unavailable for that specific story | HD may not exist for photo-only stories; `video_sd` and `photo` will still be present |

# Actor input Schema

## `facebook_urls` (type: `array`):

List of public Facebook Story URLs to process. Each URL can contain multiple individual stories.

## `include_media_metadata` (type: `boolean`):

When enabled, runs deep container-level analysis on every story file. Extracts codec, resolution, frame rate, bitrate, duration, audio sample rate, channels, and more for each video, audio, and photo.

## Actor input object example

```json
{
  "facebook_urls": [
    {
      "url": "https://www.facebook.com/stories/122093654840067130/UzpfSVNDOjI2NjM1MDI5MzQwMDYwNzQ="
    }
  ],
  "include_media_metadata": false
}
```

# 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 = {
    "facebook_urls": [
        {
            "url": "https://www.facebook.com/stories/122093654840067130/UzpfSVNDOjI2NjM1MDI5MzQwMDYwNzQ="
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapearchitect/facebook-story-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 = { "facebook_urls": [{ "url": "https://www.facebook.com/stories/122093654840067130/UzpfSVNDOjI2NjM1MDI5MzQwMDYwNzQ=" }] }

# Run the Actor and wait for it to finish
run = client.actor("scrapearchitect/facebook-story-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 '{
  "facebook_urls": [
    {
      "url": "https://www.facebook.com/stories/122093654840067130/UzpfSVNDOjI2NjM1MDI5MzQwMDYwNzQ="
    }
  ]
}' |
apify call scrapearchitect/facebook-story-downloader --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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