🌟 Facebook Reels Scraper and Advanced Metadata Extractor

Quickly extract Facebook Reels metadata (upload, views, duration, uploader, thumbnails) from one or many URLs — privacy-safe, production-ready, runs in seconds.

---

📖 One-line summary

Extracts reels-only metadata from provided Facebook URLs and stores results in Dataset + key-value store (ALL_RESULTS). Plug‑and‑play for Console, CLI, or API runs.

---

💡 Use cases / When to use

• Discover trending Facebook Reels metadata for analytics or reporting.
• Bulk-enrich content catalogs with duration, view counts, uploader info, and thumbnails.
• Monitor a list of Facebook URLs and collect standardized reel records for downstream processing.
• Quick investigations where you need reel items only (skips non-reel videos).

---

⚡ Quick Start — Apify Console (one-click)

1. Open this Actor in Apify Console.
2. Paste JSON input (see Inputs or input.example.json) into the Input tab.
3. Click Run Actor.

Runs in seconds for single URLs; built for safe, repeatable runs at scale.

---

⚙️ Quick Start — CLI & API

Run via HTTP (curl)

curl -X POST "https://api.apify.com/v2/acts/<USERNAME~ACTOR-NAME>/runs" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"startUrls":[{"url":"https://www.facebook.com/reel/EXAMPLE"}], "maxItems": 10}'

Python (apify-client) example

from apify_client import ApifyClient

client = ApifyClient('<APIFY_TOKEN>')
run = client.actor('your_username/facebook-reels-extractor').call(
    run_input={
        'startUrls': [{'url': 'https://www.facebook.com/reel/EXAMPLE'}],
        'maxItems': 10
    }
)
print('Started run:', run)

Note: Replace <APIFY_TOKEN> and your_username/facebook-reels-extractor with your account/actor id.

---

📝 Inputs (fields & schema)

Below are the primary input fields this Actor accepts. Provide them as JSON in the Console Input tab or as the POST body to the Runs API.

Console JSON example (also in input.example.json):

{
  "startUrls": [
    { "url": "https://www.facebook.com/reel/EXAMPLE" }
  ],
  "cookiesFile": null,
  "maxItems": 10
}

Fields

• startUrls — array (required): list of URLs or objects { "url": "..." } to process. The Actor runs reels-only heuristics and will skip non-reel video entries.
• cookiesFile — string (optional): path or name of a cookies file previously uploaded to the Console (useful for private or geo-restricted content).
• maxItems — integer (optional): limit total number of extracted items. 0 or omitted = no limit.

---

⚙️ Configuration

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array	✅ Yes	None	[{"url":"https://..."}]	List of Facebook URLs to scan
cookiesFile	string	⚙️ Optional	null	"fb_cookies.txt"	Upload cookies in Console if needed
maxItems	integer	⚙️ Optional	0	10	0 = unlimited; use to limit output
useApifyProxy	boolean	⚙️ Optional	false	true	Enable built-in Apify Proxy (recommended for scraping)
httpProxy	string	⚙️ Optional	None	"<PROXY_USER:PASS@HOST:PORT>"	Custom proxy; store credentials as secrets

Example Console setup: Paste the startUrls value into the Input field, set maxItems if you want to limit output, then click Run Actor.

---

📄 Outputs (Dataset / KV examples)

This Actor pushes each normalized reel record to the Dataset (push_data) and stores an aggregated JSON under the key-value store key ALL_RESULTS.

Example single-item output (dataset entry)

{
  "platform": "facebook",
  "content_type": "reel",
  "is_reel": true,
  "webpage_url": "https://www.facebook.com/reel/EXAMPLE",
  "id": "12345",
  "title": "Short sample reel",
  "description": "Short description",
  "duration_seconds": 33,
  "duration": "33 Sec",
  "duration_summary": "⏱ 33s | 0m 33s | 0.009h",
  "upload_date": "5th August 2025",
  "timestamp": 1628150400,
  "timestamp_iso": "2021-08-05T00:00:00Z",
  "view_count_raw": 12345,
  "view_count": "12.3K",
  "uploader": "example_uploader",
  "thumbnail": "https://.../thumb.jpg",
  "tags": ["tag1","tag2"],
  "raw_json": { /* original extracted record (trimmed) */ }
}

Key-value store — ALL_RESULTS contains an array of the full normalized records in application/json format.

---

🔑 Environment Variables

• APIFY_TOKEN — required for API/CLI runs outside Console. Use Console secrets to avoid plaintext tokens.
• HTTP_PROXY / HTTPS_PROXY — optional when using custom proxies (see Proxy Configuration).

---

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

• Console: Paste input → Run Actor (one-click). Results appear in Output (Dataset) and Key-value store (ALL_RESULTS).
• API: POST /v2/acts/<ACTOR_ID>/runs with JSON body equal to Console input. Use Authorization: Bearer <APIFY_TOKEN>.
• CLI: Use Apify CLI to trigger runs or view logs. Example: apify run --actor <USERNAME/ACTOR_NAME> --input input.example.json (replace placeholders).

---

⏰ Scheduling & Webhooks

• Use the Apify Console Scheduler to run this Actor periodically (e.g., hourly/daily) for continuous monitoring.
• Configure a webhook in Console to receive run finished events and download ALL_RESULTS or Dataset records automatically.

---

🕾️ Logs & Troubleshooting

• Check Run logs in Console for per-URL info (processing, skipped, or error messages).
• If a URL is skipped: verify it points to a reel URL (the Actor applies reels-only heuristics).
• If content requires a login or region restrictions, provide a cookiesFile in the Input and enable Proxy if needed.

---

🔒 Permissions & Storage Notes

• This Actor stores results in Dataset and Key-value store. Use Console roles and dataset permissions to control access.
• Never put secrets (tokens/passwords) directly in Input JSON — use Console secrets or environment variables.
• The Actor performs read-only metadata extraction (no content downloads by default).

---

🔟 Changelog / Versioning

• v1.0.0 — Initial release: reels-only metadata extraction, Dataset + ALL_RESULTS KV export.
• TODO: Add changelog entries for future releases as features or bug fixes are released.

---

🖌 Notes / TODOs

• TODO: Consider adding an option to return full media download links (opt-in) — reason: media downloads change privacy/usage requirements.
• TODO: Add richer retry/backoff configuration as a run-time input (useful for unstable networks).

---

🌍 Proxy Configuration

Enable Apify Proxy (Console): Open the Actor's Build & Storage or Proxy settings and toggle Use Apify Proxy. (One-click in Console.)

Custom proxies: Set a proxy string in the Input or environment, e.g. in Input JSON set httpProxy: "<PROXY_USER:PASS@HOST:PORT>" or set the environment variables:

export HTTP_PROXY="http://<PROXY_USER:PASS@HOST:PORT>"
export HTTPS_PROXY="http://<PROXY_USER:PASS@HOST:PORT>"

Security: Store <PROXY_USER:PASS@HOST:PORT> in Console Secrets — do not place credentials in plain Input JSON.

Advanced: TODO: Consider proxy rotation for large-scale scraping jobs to avoid rate limits and IP bans.

---

📚 References

• How to create an Actor README — Apify Docs https://docs.apify.com/academy/actor-marketing-playbook/actor-basics/how-to-create-an-actor-readme

• Apify API Client for Python — Apify Docs https://docs.apify.com/api/client/python/

• Apify CLI — Apify Docs https://docs.apify.com/cli/

---

🤔 What I inferred from main.py

• This Actor accepts startUrls, cookiesFile, and maxItems as the primary inputs.
• It applies "reels-only" heuristics per URL and normalizes extracted metadata into a consistent record shape.
• Outputs: pushes individual records to the Dataset and writes the aggregated array to the key-value store under ALL_RESULTS.
• Network activity is present (external webpage extraction), therefore Proxy configuration is exposed in this README.
• Supports cookies for access to restricted content and a maxItems limiter to control run size.

---

End of README.md

--- input.example.json --- { "startUrls": [ { "url": "https://www.facebook.com/reel/EXAMPLE" } ], "cookiesFile": null, "maxItems": 10, "useApifyProxy": true }

--- CONFIG.md ---

CONFIG.md — quick notes for Console maintainers

• Default run behavior: runs in "reels-only" mode. Non-reel content is skipped and logged.
• Secrets: Add APIFY_TOKEN and any proxy credentials to Console Secrets under Project settings.
• Artifacts: Dataset contains item-level records. ALL_RESULTS key in Key-value store contains the full aggregated JSON array.
• Monitoring: Use Scheduler + Webhook to automate downstream processing.

Enjoy the actor dear ❤️