🌟 Facebook Reels & Video Downloader — Fast, Reliable, Production-Ready

One-line hero: Instantly extract Facebook Reels and videos as H.264 MP4s with thumbnails and structured metadata — paste URLs, click Run, and get secure, production-ready outputs in seconds. 🚀🔒

---

📖 Short summary

This Actor fetches duration, thumbnail and optionally downloads H.264 MP4 media for Facebook Reels and videos, then stores results in Dataset and Key‑Value Store for immediate use in pipelines and workflows.

---

💡 Use cases — when to use

• Archive short-form Reels or longer Facebook videos for audits or content libraries.
• Pull ready-to-use MP4s and thumbnails for republishing, editing, or analytics.
• Feed media into ML datasets, content pipelines, or CMS imports.

---

⚡ Quick Start — Console (one-click)

1. Open this Actor in Apify Console.
2. Paste one or more Facebook Reel or Video URLs into the Input editor (see Input example).
3. Click Run — results appear in Dataset & Key‑Value Store.

Tip: add a GIF or short screenshot to the hero area for higher conversion.

---

⚙️ Quick Start — CLI & API

CLI (one-liner)

$apify run --actor <OWNER>/<ACTOR_NAME> --input input.example.json

Python (apify-client)

from apify_client import ApifyClient
client = ApifyClient('<APIFY_TOKEN>')
run = client.actors.run_actor(actor_id='<OWNER>/<ACTOR_NAME>', input={"startUrls":["https://www.facebook.com/watch/?v=123"]})
print('Run started:', run['id'])

---

📝 Inputs (fields & schema)

Console JSON input example (also included as input.example.json):

{
  "startUrls": ["https://www.facebook.com/watch/?v=123456789", "https://www.facebook.com/reel/12345"],
  "download": true,
  "download_merged": true,
  "desired_resolution": "1080p",
  "preserve_downloads": false,
  "cookiesFile": "cookies.txt",
  "proxyConfiguration": {"useApifyProxy": true},
  "maxConcurrency": 5
}

• startUrls — array of Facebook video or reel URLs (required).
• download — boolean: enable media downloads (default: false).
• download_merged — boolean: prefer merged video+audio MP4 (default: true).
• desired_resolution — string: target max resolution (e.g., 720p, 1080p).
• preserve_downloads — boolean: keep local copies after upload (default: false).
• cookiesFile — optional path to cookie file for gated content. (TODO: confirm exact format.)
• proxyConfiguration — object: Apify Proxy or custom proxies.
• maxConcurrency — integer: concurrency limit (default: 5).

---

⚙️ Configuration (friendly table)

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array	✅ Yes	None	["https://.../watch/?v=123"]	Facebook Reels & Video URLs
url / startUrl	string	⚠️ Optional	None	"https://.../watch/?v=123"	Alternate single-url input key
download	boolean	⚠️ Optional	false	true	Toggle media download
download_merged	boolean	⚠️ Optional	true	true	Prefer merged MP4 output
desired_resolution	string	⚠️ Optional	"1080p"	"720p"	Maximum height to attempt
preserve_downloads	boolean	⚠️ Optional	false	true	Keep files in output/
cookiesFile	string	⚠️ Optional	None	"cookies.txt"	For private/gated content (TODO)
proxyConfiguration	object	⚙️ Optional	{}	{"useApifyProxy": true}	Apify Proxy or custom proxies
maxConcurrency	integer	⚠️ Optional	5	10	Concurrency control

---

📄 Outputs (Dataset / KV examples)

Inferred example output item:

{
  "platform": "facebook",
  "original_url": "https://web.facebook.com/share/v/1AfqRqQm47/",
  "_source_index": 4,
  "_scraped_at": "2025-11-23T09:29:28.374713Z",
  "yt_info": { "id": "1202940488392514", "title": "Sample Title", "duration": 17.866, "thumbnail": "https://...jpg" },
  "title": "Sample Title",
  "duration": 17.866,
  "thumbnail": "https://...jpg",
  "kv_files": { "final": { "kv_key": "MEDIA_1202940488392514_final.mp4", "local": null } },
  "download_links": {
    "final_kv": "MEDIA_1202940488392514_final.mp4",
    "final_local": "/app/output/Safe_File_Name.mp4",
    "final_direct_url": "https://api.apify.com/v2/key-value-stores/~/records/MEDIA_1202940488392514_final.mp4"
  }
}

Note: exact fields and presence of local depend on preserve_downloads and whether the file was uploaded to KV.

---

🔑 Environment variables & secrets

• <APIFY_TOKEN> — store as a secret in Apify Console (do not hardcode).
• <PROXY_USER:PASS@HOST:PORT> — placeholder for custom proxy credentials.
• HTTP_PROXY / HTTPS_PROXY — optional env vars for custom proxy usage.

---

▶️ How to Run (Console, CLI, API)

Console

1. Open the Actor page in Apify Console.
2. Paste the sample JSON into the Input editor or upload input.example.json.
3. (Optional) Toggle Apify Proxy in run settings.
4. Click Run and inspect Dataset & Key‑Value Store.

CLI

• apify run --actor <OWNER>/<ACTOR_NAME> --input input.example.json

API

• Use the Python apify-client snippet above with <APIFY_TOKEN>.

---

⏰ Scheduling & Webhooks

• Schedule the Actor in Console (cron-style) for recurring exports.
• Configure a webhook in Actor settings to receive a POST when a run completes (include dataset URL).

---

🕾️ Logs & Troubleshooting

• View live run logs in Apify Console Run view.

• Common quick fixes:

  • No output / "No startUrls provided" — ensure startUrls contains valid Reel/video URLs.
  • Download failed — set download=true and check desired_resolution.
  • Authentication required — provide cookiesFile or use a proxy with access.
  • Rate limiting / blocks — enable Apify Proxy or reduce maxConcurrency.

---

🔒 Permissions & Storage Notes

• Uses Dataset for JSON rows and Key‑Value Store for media files. Local output/ is temporary unless preserve_downloads is true.
• Store secrets in Apify Console secret storage. The Actor does not expose stored secrets in logs by default.

---

🔟 Changelog (example)

• 1.0.0 — Initial release: metadata extraction + H.264 MP4 download, Dataset + KV outputs.

---

🖌 Notes / TODOs

• TODO: confirm cookiesFile expected format — inferred but not explicit in source.
• TODO: add demo GIF/screenshots for the Quick Start hero.

---

🌍 Proxy Configuration

• Enable Apify Proxy (Console): In run configuration, toggle Use Apify Proxy.

• Custom proxy example:

  • HTTP_PROXY / HTTPS_PROXY env example: http://<PROXY_USER:PASS@HOST:PORT>
  • Input example for custom proxy:

{"proxyConfiguration": {"useApifyProxy": false, "proxyUrls": ["http://<PROXY_USER:PASS@HOST:PORT"]}}

• Security reminder: store proxy credentials as secrets, not plaintext.
• TODO: Consider proxy rotation for large-scale scraping.

---

📚 References (official Apify docs)

• Actor README guidelines (official)
• Input/Output schema docs (official)
• CLI & API usage docs (official)

---

🤔 What I inferred from main.py

• The Actor performs network extraction and uploads media to Key‑Value Store and Dataset.
• Inputs: startUrls/url, download, download_merged, desired_resolution, cookiesFile, proxyConfiguration, maxConcurrency.
• Outputs: dataset rows with metadata and KV records for final MP4 files.
• The Actor supports both Facebook Reels and standard Facebook video URLs.

---

Why this Actor? Plug-and-play Reels & video downloader that returns production-ready MP4s and metadata — secure, fast, and built for scale. Run this Actor on Apify Console — get instant results in seconds.

CONFIG — Advanced Settings & Notes

Cookie file guidance

• cookiesFile is optional. Use when accessing private or age-restricted content.
• Upload cookies to Apify Key-Value and reference the path, or use Console secret storage.
• TODO: confirm exact cookie file format expected by the Actor.

Proxy recommendations

• Enable Apify Proxy for large-scale and resilient runs.
• For custom proxies, set proxyConfiguration.proxyUrls or HTTP_PROXY/HTTPS_PROXY.
• Never store proxy credentials in source; use Apify secrets.

Performance tips

• Lower maxConcurrency when you observe rate limiting.
• Reduce desired_resolution to speed up downloads and save bandwidth.