🎯 Facebook Video Metadata Scraper

Extract structured metadata from Facebook videos and Reels directly on the Apify platform.

---

📖 Summary

This Actor takes one or more Facebook video or Reel URLs and produces structured JSON metadata (title, uploader, view counts, upload dates, thumbnails, tags, etc.). Results are pushed to the default Dataset and also consolidated under the ALL_RESULTS key in the Key-Value Store.

---

💡 Use cases / When to use

• Market research and trend analysis on Facebook video performance.
• Monitoring competitor video engagement (views, likes, comments).
• Collecting structured data for analytics dashboards.
• Archiving Facebook video metadata without downloading full media.

---

⚡ Quick Start (Console)

1. Go to your Actor in Apify Console.

2. Click Run.

3. In the Input tab, paste JSON like:

   {
     "startUrls": [
       {"url": "https://www.facebook.com/reel/1234567890123456"}
     ],
     "maxItems": 5
   }
   

4. Click Run.

5. Check the Dataset tab for extracted items, or Key-Value Store for the consolidated ALL_RESULTS file.

---

⚡ Quick Start (CLI + API)

CLI (apify-cli)

$apify run -p input.json

Where input.json contains:

{
  "startUrls": [
    {"url": "https://www.facebook.com/reel/1234567890123456"}
  ]
}

API (apify-client in Python)

from apify_client import ApifyClient

client = ApifyClient('<APIFY_TOKEN>')
run = client.actor('<ACTOR_ID>').call(run_input={
    "startUrls": [{"url": "https://www.facebook.com/reel/1234567890123456"}],
    "maxItems": 5
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

---

📝 Inputs

• startUrls (array of objects or strings, required) — Facebook video or Reel URLs to process.
• cookiesFile (string, optional) — Path to uploaded cookies file. Useful for login-required videos.
• proxyConfiguration (object, optional) — Proxy settings configured in Apify Console.
• maxItems (integer, optional) — Maximum number of items to scrape.

---

⚙️ Configuration

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	📝 Notes
startUrls	array	✅ Yes	null	[ {"url": "https://facebook.com/reel/..."} ]	List of URLs to scrape
cookiesFile	string	❌ No	null	cookies.txt	Upload via Apify key-value store
proxyConfiguration	object	❌ No	{}	{ "useApifyProxy": true }	Configure in Console → Proxy
maxItems	integer	❌ No	0 (no limit)	50	Limit number of items processed
ALL_RESULTS	dataset	Auto	n/a	Key-Value Store entry	Consolidated JSON array of all results

➡️ Example: In Console → Run → Input, paste:

{
  "startUrls": [ {"url": "https://www.facebook.com/reel/1234567890123456"} ]
}

---

📤 Outputs

Each processed video produces a JSON object like:

{
  "platform": "facebook",
  "webpage_url": "https://www.facebook.com/reel/1234567890123456",
  "id": "1234567890123456",
  "title": "Sample video",
  "duration": "25s",
  "upload_date": "16th September 2025",
  "timestamp_iso": "2025-09-16T10:30:00Z",
  "view_count": "2.3K",
  "like_count": 150,
  "comment_count": 20,
  "uploader": "Page Name",
  "thumbnail": "https://...jpg"
}

• All items → Default Dataset.
• Consolidated array → Key-Value Store entry ALL_RESULTS.

---

🔑 Environment variables

• APIFY_TOKEN — Required for API or CLI usage.
• HTTP_PROXY / HTTPS_PROXY — Only if custom external proxies are used.

---

▶️ How to Run

In Apify Console

1. Open Actor → Run.
2. Paste input JSON into Input.
3. Run → View results in Dataset and Key-Value Store.

CLI

$apify call <ACTOR_ID> -p input.json

API

See the Python snippet above under Quick Start.

---

⏰ Scheduling & Webhooks

• Configure in Console → Schedule to run hourly/daily.
• Add webhooks in Console → Webhooks to trigger on success/failure.

---

🐞 Logs & Troubleshooting

• View run logs in Console → Runs → select a run.

• Common errors:

  • No startUrls provided. → Ensure you set startUrls.
  • Empty dataset → The link was invalid or required login without cookies.

---

🔒 Permissions & Storage notes

• Output is saved to the Actor’s default Dataset and Key-Value Store.
• If using cookies, upload them securely in Apify storage.

---

🆕 Changelog / Versioning tip

• Increment Actor version when input schema or output fields change.

---

📌 Notes / TODOs

• TODO: Confirm how cookiesFile should be uploaded (default key-value store vs. dataset file input).
• TODO: Document any rate-limits when scraping high volumes of URLs.

---

🌍 Proxy configuration

• In Console → Run → Proxy, enable Apify Proxy with one click.

• To use your own proxy: In Console → Actor settings → Environment variables, set:

  • HTTP_PROXY = http://<USER>:<PASS>@<HOST>:<PORT>
  • HTTPS_PROXY = http://<USER>:<PASS>@<HOST>:<PORT>

• Always store credentials as secrets in Apify.

• TODO: Advanced proxy rotation and load balancing patterns can be added later.

---

📚 References

• Apify Input & Output docs
• Apify Proxy documentation
• Apify Scheduling & Webhooks

---

🧐 What I inferred from main.py

• Actor requires startUrls as input.
• Optional inputs: cookiesFile, proxyConfiguration, maxItems.
• Outputs go to both Dataset and Key-Value Store key ALL_RESULTS.
• Proxy usage is supported, hence Proxy section included.
• Marked TODOs for cookie upload method and possible rate limits.