🌟 Facebook Video Downloader — Instant, Reliable Video Exports

One-line hero: Instantly fetch production-ready Facebook videos (H.264/MP4) — plug into Apify Console, run at scale, and store outputs securely.

---

📖 What this Actor does

This Apify Actor extracts and downloads Facebook video content into MP4 (H.264) containers and stores results in the Apify dataset and Key-Value store. It is designed for fast, repeatable runs with safe defaults and optional proxy support.

Why it helps: save time, avoid manual downloads, and get consistent video files ready for analytics, archiving, or publishing workflows.

---

💡 Use cases / When to use

• Bulk-export Facebook page videos for archiving or content audits.
• Quickly fetch a single video for review or republishing.
• Automated video ingestion into a media pipeline (transcoding, indexing, metadata).

---

⚡ Quick Start — Console (One-Click)

1. Open this Actor in Apify Console.
2. Paste or select startUrls (Facebook video page URLs) in the Input editor.
3. Click Run — results appear in Dataset & Key-Value Store.

---

⚙️ 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=123456789"]})
print('Run started:', run['id'])

---

📝 Inputs (fields & example)

Place a JSON input in the Console Input editor or pass via CLI/API. See input.example.json for a ready sample.

Minimal input schema (example)

{
  "startUrls": [
    "https://www.facebook.com/watch/?v=123456789"
  ],
  "download": true,
  "desired_resolution": "1080p",
  "preserve_downloads": false
}

---

⚙️ Configuration — Inferred Input Fields

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes (inferred)
startUrls	array	✅ Yes	None	["https://.../watch/?v=123"]	List of Facebook video page URLs.
url / startUrl	string	⚠️ Optional	None	"https://.../watch/?v=123"	Alternate single-url input key (detected in code).
cookiesFile	string	⚠️ Optional	None	"/tmp/cookies.txt"	Path to cookie file for gated content. TODO: confirm format.
desired_resolution	string	⚠️ Optional	"1080p"	"720p"	Max height to attempt when downloading.
download	boolean	⚠️ Optional	false	true	If true, actor attempts to download media files.
download_merged	boolean	⚠️ Optional	true	true	If true + download, tries merged video+audio output.
preserve_downloads	boolean	⚠️ Optional	false	true	If true, keeps local copies in output/.
proxyConfiguration	object	⚙️ Optional	{}	{"useApifyProxy": true}	Apify Proxy or custom proxy settings.
maxConcurrency	integer	⚠️ Optional	5	10	Controls concurrent downloads.

Console tip: Paste the sample JSON (above or in input.example.json) into the Input field, then click Run Actor.

---

📄 Outputs (Dataset / KV examples)

Outputs are written to the Actor Dataset and optionally to the Key-Value store (direct download links). Example single-item output (Dataset row):

{
    "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": "বন্ধুত্ব এমন হোক; শেষ বয়সে এসেও এইভাবেই একসাথে বসে আড্ডা দেওয়া যায় 🖤",
      "duration": 17.866,
      "thumbnail": "https://scontent-iad3-1.xx.fbcdn.net/v/t15.5256-10/588474108_2065818280875137_3795829089873921437_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=102&ccb=1-7&_nc_sid=50ce42&_nc_ohc=emzxEIOmJtcQ7kNvwHu2QQ-&_nc_oc=Adn3erpPJY9ttKkBXqvEp4I9Anb8qn6r79l_ZCDWxS9QLFkD3qD88mQUbaHhDvvj364&_nc_zt=23&_nc_ht=scontent-iad3-1.xx&_nc_gid=cY_ThWNpBWTrRDXASSknww&oh=00_AfjNwEhRTtPFdqGYdGPrtRcJ0E6rFi2vjCTlX9wT_M0D-g&oe=6928B3D5"
    },
    "title": "বন্ধুত্ব এমন হোক; শেষ বয়সে এসেও এইভাবেই একসাথে বসে আড্ডা দেওয়া যায় 🖤",
    "duration": 17.866,
    "thumbnail": "https://scontent-iad3-1.xx.fbcdn.net/v/t15.5256-10/588474108_2065818280875137_3795829089873921437_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=102&ccb=1-7&_nc_sid=50ce42&_nc_ohc=emzxEIOmJtcQ7kNvwHu2QQ-&_nc_oc=Adn3erpPJY9ttKkBXqvEp4I9Anb8qn6r79l_ZCDWxS9QLFkD3qD88mQUbaHhDvvj364&_nc_zt=23&_nc_ht=scontent-iad3-1.xx&_nc_gid=cY_ThWNpBWTrRDXASSknww&oh=00_AfjNwEhRTtPFdqGYdGPrtRcJ0E6rFi2vjCTlX9wT_M0D-g&oe=6928B3D5",
    "kv_files": {
      "final": {
        "kv_key": "MEDIA_1202940488392514_final.mp4",
        "local": null
      }
    },
    "download_links": {
      "final_kv": "MEDIA_1202940488392514_final.mp4",
      "final_local": "/app/output/বন_ধ_ত_ব_এমন_হ_ক__শ_ষ_বয়স__এস_ও_এইভ_ব_ই_একস_থ__বস__আড_ড__দ_ওয়__য_য়.mp4",
      "final_direct_url": "https://api.apify.com/v2/key-value-stores/~/records/MEDIA_1202940488392514_final.mp4"
    }
  },

Note: exact fields and structure have been inferred. TODO: confirm final output schema.

---

🔑 Environment variables & secrets

• <APIFY_TOKEN> — store as a secret in Apify Console (do not hardcode).
• <PROXY_USER:PASS@HOST:PORT> — placeholder for custom proxies.
• HTTP_PROXY / HTTPS_PROXY — can be set as environment variables when using custom proxies.

---

▶️ How to Run (step-by-step)

Console (recommended)

1. Open Actor in Apify Console.
2. Paste input.example.json into the Input editor.
3. (Optional) Configure the Input schema in Actor settings.
4. Click Run and monitor Dataset/Key-Value results.

CLI

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

API (apify-client)

• Use the Python snippet above; replace <APIFY_TOKEN> and <OWNER>/<ACTOR_NAME>.

---

⏰ Scheduling & Webhooks

• Schedule runs in Console using the built-in scheduler (cron-style).
• Configure a webhook in Actor settings to receive a POST when a run finishes (include dataset URL).

---

🕾️ Logs & Troubleshooting

• View live logs in Apify Console Run view.

• Common quick fixes:

  • Missing output / "Download failed" — check download input; ensure the URL is a Facebook video (Reels are skipped).
  • Authentication required — provide cookiesFile or use a proxy that has access.
  • Rate limits / block — enable Apify Proxy or configure a custom proxy.

---

🔒 Permissions & Storage Notes

• Output locations: Dataset (rows) and Key-Value Store (media files). Local output/ is used during processing and may be removed after KV upload unless preserve_downloads is true.
• Privacy: store secrets only in Console secret storage. Actor does not leak tokens in logs by default.

---

🔟 Changelog (example)

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

---

🖌 Notes / TODOs

• TODO: confirm output schema — fields were inferred from runtime behaviour.
• TODO: add demo GIF/screenshots (replace the placeholder image in the Quick Start section).

---

🌍 Proxy Configuration

Enable Apify Proxy (Console): In Apify Console > Actor run configuration, toggle Use Apify Proxy or provide proxyConfiguration input.

Custom proxy example (store credentials as secrets):

• 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 note: never commit credentials; save them in Apify Console secrets or environment variables.

TODO: Consider proxy rotation for large-scale scraping.

---

📚 References (official Apify docs)

1. How to write a great README for your Actors — Apify Help. citeturn0search3
2. Actor input schema specification — Apify Docs. citeturn0search4
3. Apify API Client for Python — Apify Docs. citeturn0search2

---

🤔 What I inferred from main.py

• The Actor performs network requests to fetch video metadata and media (proxy support required).
• Inputs include startUrls / url, resolution caps, download toggles, cookie file reference, and proxy configuration.
• Outputs are stored in the Dataset and Key-Value Store with media files uploaded under safe keys.
• Reels detection exists and Reels are explicitly skipped by this actor.

---

Why this Actor?

• Production-ready and privacy-aware: designed for safe, repeatable bulk downloads.
• Plug-and-play: paste a Facebook video URL and run — results in seconds.

Run this Actor on Apify Console — get instant results in seconds.