🎯 Facebook Video Scraper — Apify Actor

Hero: Instant, privacy-safe extraction of Facebook video metadata and direct media URLs — production-ready and easy to run from Apify Console.

---

📖 One-line summary

Turn Facebook video links into clean, structured JSON (URLs, titles, stats, and multiple duration formats) — no code changes required in Console.

---

💡 Use cases — When to use

• Monitor public pages for trending videos and engagement signals.
• Feed reliable video URLs into transcription, summarization, or indexing pipelines.
• Build content audits or competitor intelligence dashboards.
• Bulk-export media links and metadata for analytics teams.

---

⚡ Quick Start — Console (one-click)

1. Open this Actor in Apify Console.
2. Paste the example input (see Inputs section) into the Input tab.
3. Click Run — results appear in the Dataset when the run completes.

---

⚙️ Quick Start — CLI & API

CLI (apify-cli)

# Run with a simple input file
apify run --input input.example.json

Python — apify-client

from apify_client import ApifyClient
client = ApifyClient('<APIFY_TOKEN>')
run_input = {"facebookVideoUrls": ["https://www.facebook.com/watch?v=1234567890"]}
run = client.actor('your-username/facebook-video-scraper').call(run_input=run_input)
print('Run started:', run['id'])

---

📝 Inputs (fields & schema)

Paste JSON into the Actor Input field in Console. Minimal example is in input.example.json (in Canvas).

Schema (key fields):

• facebookVideoUrls (array[string]) — required. One or more Facebook watch/post URLs.
• maxVideos (integer) — optional. Limit processed items.
• cookiesFile (string) — optional. Key-value store name of a cookies file for logged-in scraping.
• proxyConfig (object) — optional. Proxy settings (Apify Proxy or custom).

---

⚙️ Configuration

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
username	string	✅ Yes	None	"tiktok_user123"	Target username to fetch info for (optional alias).
proxyConfig	object	⚙️ Optional	{}	{"useApifyProxy": true}	Proxy settings (use Apify Proxy or custom credentials).

Example Console setup: Paste "tiktok_user123" into the Input field under username, then click Run Actor.

---

📄 Outputs (Dataset / KV examples)

The actor writes results to the default Dataset and to a key-value store ALL_RESULTS. Each record is a compact JSON object with metadata and multiple duration formats.

Output example

{
  "id": "1234567890",
  "title": "Funny Cat Compilation",
  "description": "The funniest cats of 2025",
  "upload_date": "1st October 2025",
  "timestamp": 1696158720,
  "timestamp_iso": "2025-10-01T14:32:00Z",
  "view_count": "154.3K",
  "like_count": 9200,
  "comment_count": 142,
  "videoUrl": "https://video.xx.fbcdn.net/v/t42.9040-2/...",
  "thumbnail": "https://scontent.xx.fbcdn.net/v/t15.5256-10/...",
  "duration_seconds": 97.0,
  "duration": "1m 37s",
  "duration_display": "1 Minute 37 Seconds (0.0270 Hours)",
  "duration_full": {
    "in_seconds": "97 Seconds",
    "in_minutes": "1 Minutes 37 Seconds",
    "in_hours": "0 Hours 1 Minutes 37 Seconds"
  },
  "duration_summary": "⏱ 97s | 1m 37s | 0h 1m 37s",
  "duration_decimal_hours": 0.027,
  "duration_decimal_minutes": 1.62,
  "raw_json": { }
}

---

🔑 Environment Variables

• <APIFY_TOKEN> — used by the Apify Console/CLI when calling via API.
• <PROXY_USER:PASS@HOST:PORT> — placeholder for custom proxy credentials (store as a secret).
• FB_COOKIES — optional placeholder for a cookies file name in key-value store when scraping private/restricted videos.

TODO: Replace placeholders with secrets via Console Secret Manager. Never paste credentials directly into Input.

---

▶️ How to Run

Console

1. Open the Actor page.
2. Paste input.example.json into Input.
3. Click Run — monitor progress in Logs and Dataset.

CLI

$apify run --input input.example.json

API Use the Python snippet above (apify-client) — call the actor with run_input and poll the run result.

---

⏰ Scheduling & Webhooks

• Schedule runs in Console using the Scheduler to automate daily or hourly collection.
• Configure Webhooks in Apify to receive run-complete notifications and processed payloads.

---

🕾️ Logs & Troubleshooting

• If extraction fails for certain URLs, enable proxy and provide a cookiesFile for logged-in access.
• Check the Logs tab for extractor errors — common causes: region restrictions, private content, or temporary changes to the source site.
• If you see parsing errors, try toggling proxy or updating cookies.

---

🔒 Permissions & Storage Notes

• The Actor writes to the default Dataset and ALL_RESULTS key in Key-Value store.
• Do not store credentials in public Datasets. Use Apify Secret Manager for sensitive data.
• This Actor is designed to respect privacy and collect only publicly accessible metadata unless you provide valid cookies.

---

🔟 Changelog / Versioning

• v1.0.0 — Production-ready release: reliable extraction, multi-format durations, Console-friendly inputs.
• Future minor releases will focus on extractor resilience and proxy handling improvements.

---

🖌 Notes / TODOs

• TODO: Add explicit example of cookiesFile creation and upload instructions (reason: varies by user/browser).
• TODO: Consider adding native retry/backoff settings in Input schema for large-scale runs.

---

🌍 Proxy Configuration

Using proxies improves reliability when scraping public platforms:

• Apify Proxy (recommended) — enable useApifyProxy in the Input Proxy object in Console.
• Custom proxies — supply credentials in secret form: <PROXY_USER:PASS@HOST:PORT>.

Environment examples

# example environment variables (place these in your secret manager, not in plain input)
HTTP_PROXY="http://<PROXY_USER:PASS@HOST:PORT>"
HTTPS_PROXY="http://<PROXY_USER:PASS@HOST:PORT>"

Security note: Store proxy credentials as secrets, not plaintext. Do not hard-code credentials into Input.

TODO: Consider proxy rotation for large-scale scraping to minimize IP throttling.

---

📚 References

• Apify Actor best practices — official Console documentation. (Reference link placeholder)
• Apify Input / Output schema guide — reference doc (placeholder)
• Apify CLI & API quickstart — reference doc (placeholder)

---

🤔 What I inferred from main.py

• This Actor accepts a list of Facebook video/post URLs and extracts metadata and direct media URLs.
• Results are written to Dataset and a key-value store for easy download.
• Multiple duration formats are provided: human-readable, compact summary, decimals (minutes/hours) and raw seconds.
• Optional cookies and proxy support are inferred to handle private or geo-restricted content.

---

Run this Actor on Apify Console — get instant, structured video metadata in seconds.