facebook-reels-downloader

Extract Facebook Reels metadata, optimized for stability and fastest possible extraction.

---

What this Actor does

This actor accepts an array of Facebook Reels URLs, analyzes each with a media metadata extractor to discover available formats, selects the best video and audio streams, and pushes a structured record into the default dataset. No media files are downloaded by default; it only extracts metadata and direct stream URLs.

---

Features

• ✅ Extracts metadata (title, duration, description, thumbnail) from Facebook Reels.
• ✅ Selects best candidate video-only and audio-only streams when available.
• ✅ Falls back to combined streams if separate audio/video streams are not found.
• ✅ Pushes one structured JSON row per input URL into the default Apify dataset.
• ✅ Accepts both { "url": "..." } objects and raw string arrays as input.
• ✅ Safe error handling: failed extractions produce an item with an error field instead of crashing.

---

Configuration / Environment

The actor reads its configuration from the Apify input (JSON). You can also pass inputs via environment variables in local runs.

Input field summary (mini-table):

• startUrls — array — required — default: none (schema prefill shown)

• items: object with url string, or string directly.

• one-line description: List of Facebook Reels to extract.

---

Outputs

The actor pushes one JSON record per processed input to the default dataset using the platform push_data mechanism. It does not store credentials in outputs.

Dataset record structure (fields → type → description)

• url → string → The original input URL (redact any sensitive tokens in consumer-facing usage).
• title → string | → Media title extracted from metadata.
• duration → number | → Duration in seconds.
• description → string | → Text description for the reel.
• thumbnail_url → string | → URL to the thumbnail image.
• video_download_url → string | → Direct URL to the selected video stream (may be the same as audio_download_url when only combined streams exist).
• audio_download_url → string | → Direct URL to the selected audio stream.
• _best_video_format → object | → Short info about the chosen video format:

---

Example INPUT.json and OUTPUT.json

Example INPUT.json

{
    "startUrls": [
        {
            "url": "https://www.facebook.com/reel/1289152909325322",
            "method": "GET"
        },
        {
            "url": "https://www.facebook.com/reel/1258774319274887",
            "method": "GET"
        },
        {
            "url": "https://www.facebook.com/share/v/1D9H5Bwyjg/",
            "method": "GET"
        }
    ]
}

Example OUTPUT.json

[
  {
    "url": "https://www.facebook.com/reel/1289152909325322",
    "title": "1.3M views · 1.4M reactions | Joshua Platillero on Reels",
    "duration": 15.2,
    "description": "",
    "thumbnail_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t51.71878-10/544086226_815766004122299_421912078125499552_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=102&ccb=1-7&_nc_sid=50ce42&_nc_ohc=H0YFZ_eI4zYQ7kNvwHw0ifO&_nc_oc=AdlYGSBkT9hrmFmmftKBYXJ0ns14wV1igjth2Z_YPtzGygUW2p4FXiIWDS8GLp-azfY&_nc_zt=23&_nc_ht=scontent-iad3-1.xx&_nc_gid=2zF2v7zCj_v7Go9L29FgBg&oh=00_AflHwW0Rb9sxwtg0ggRe0NbOylpC285WNvGTiHbCAHXp5g&oe=6939B807",

    "video_download_url": "https://video-iad3-1.xx.fbcdn.net/o1/v/t2/f2/m367/AQPvmVvMCYaxW5NuO6gsaIJq-hLLIH65oNhgjSLgsW2oaGV94kBBLFTb-w_anO8yFUr_hF_3cyT_djl-OlMECHZrsYofvF8rcVtVtBg.mp4?_nc_cat=110&_nc_sid=9ca052&_nc_ht=video-iad3-1.xx.fbcdn.net&_nc_ohc=lxdU3DCs19UQ7kNvwGyGzOn&efg=eyJ2ZW5jb2RlX3RhZyI6ImRhc2hfcjJhdjEtcjFnZW4ydnA5X3E5MCIsInZpZGVvX2lkIjoxMjg5MTUyOTA5MzI1MzIyLCJvaWxfdXJsZ2VuX2FwcF9pZCI6MCwiY2xpZW50X25hbWUiOiJ1bmtub3duIiwieHB2X2Fzc2V0X2lkIjo4MDMyODkxMDg3MTMzNTYsImFzc2V0X2FnZV9kYXlzIjo4NSwidmlfdXNlY2FzZV9pZCI6MTAwOTksImR1cmF0aW9uX3MiOjE1LCJiaXRyYXRlIjoyOTQyODI0LCJ1cmxnZW5fc291cmNlIjoid3d3In0=&ccb=17-1&_nc_gid=2zF2v7zCj_v7Go9L29FgBg&_nc_zt=28&oh=00_AflST1C8hYGgAnZrxQorSyVsraTjKFA83qxd1eypA_etdw&oe=6939D497",
    "audio_download_url": "https://video-iad3-2.xx.fbcdn.net/o1/v/t2/f2/m69/AQNH-_NkWPzG5Io4otCAOEfJFTrUnlVUqntr0bFw2R5V6jN9kqKa7S-uONTP1I2bMg7hgiUVnJvz8fKTRgG6I9eq.mp4?strext=1&_nc_cat=106&_nc_sid=9ca052&_nc_ht=video-iad3-2.xx.fbcdn.net&_nc_ohc=mPoMizK9GPEQ7kNvwHcNkkk&efg=eyJ2ZW5jb2RlX3RhZyI6ImRhc2hfbG5faGVhYWNfdmJyM19hdWRpbyIsInZpZGVvX2lkIjoxMjg5MTUyOTA5MzI1MzIyLCJvaWxfdXJsZ2VuX2FwcF9pZCI6MCwiY2xpZW50X25hbWUiOiJ1bmtub3duIiwieHB2X2Fzc2V0X2lkIjo4MDMyODkxMDg3MTMzNTYsImFzc2V0X2FnZV9kYXlzIjo4NSwidmlfdXNlY2FzZV9pZCI6MTAwOTksImR1cmF0aW9uX3MiOjE1LCJiaXRyYXRlIjo4MTMxOSwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=2zF2v7zCj_v7Go9L29FgBg&_nc_zt=28&oh=00_Afku7g1eFg3NstZG8_-fZSkObY25-lbgEpwlkgL9XE-30A&oe=6939D784",

    "_best_video_format": {
      "id": "1177453347540673v",
      "ext": "mp4",
      "height": 1920
    },
    "_best_audio_format": {
      "id": "633970056179769a",
      "ext": "m4a",
      "abr": 80.819
    },
    "_raw_info": {
      "id": "1289152909325322",
      "uploader": "Joshua Platillero",
      "webpage_url": "https://m.facebook.com/watch/?v=1289152909325322&_rdr"
    }
  },
  {
    "url": "https://www.facebook.com/reel/1258774319274887",
    "title": "\"Watch This in 4K 😍 | You Won't Believe This Shot! 🔥✨ #4KVideo #ViralReel\" #4K #4KReels #ReelsViral #ReelsInstagram #ViralVideo #TrendingReels #InstaReels #ReelsExplore #ExplorePage #InstaTrend #Reels2025 #CinematicReels #UltraHD #SmoothReels #ReelsOfInstagram #ContentCreator #ViralContent #ReelsLovers #IGReels #CreativeReels #MustWatch | TECHSUNIL.ve77",
    "duration": 6.969,
    "description": "\"Watch This in 4K 😍 | You Won't Believe This Shot! 🔥✨ #4KVideo #ViralReel\"\n#4K #4KReels #ReelsViral #ReelsInstagram #ViralVideo #TrendingReels #InstaReels #ReelsExplore #ExplorePage #InstaTrend #Reels2025 #CinematicReels #UltraHD #SmoothReels #ReelsOfInstagram #ContentCreator #ViralContent #ReelsLovers #IGReels #CreativeReels #MustWatch",
    "thumbnail_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t15.5256-10/514764040_661024096988112_4974040658872884595_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=110&ccb=1-7&_nc_sid=50ce42&_nc_ohc=WACc64YdLTEQ7kNvwHOheAM&_nc_oc=AdmshiPxWOqzb-EKzPhyywNKZuGR2_R6kowW3sH2sWqsNDcwnWRhHYQIiL1IB3bVISE&_nc_zt=23&_nc_ht=scontent-iad3-1.xx&_nc_gid=A1kLKuY6ivheRz7ht8Zxsw&oh=00_AfkcC-riIldoGQPORwOuXjtpklQ0LkNYBtJb7-puxqx8PQ&oe=6939B8D1",

    "video_download_url": "https://video-iad3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQO0ky87UIg30cJExxKjGWkZlIjkh_qy-1qjtY3zkm-rZzeTsGuTgQu4SMZvF3h7FJe-0BrN4r_XAcZ8VCi3tW2DfnvPm-SrLzZ5HDxksLWqdQ.mp4?_nc_cat=104&_nc_sid=9ca052&_nc_ht=video-iad3-1.xx.fbcdn.net&_nc_ohc=-C4ItF_RnwMQ7kNvwGeabQF&efg=eyJ2ZW5jb2RlX3RhZyI6ImRhc2hfdnA5LWJhc2ljLWdlbjJfNzIwcCIsInZpZGVvX2lkIjoxMjU4Nzc0MzE5Mjc0ODg3LCJvaWxfdXJsZ2VuX2FwcF9pZCI6MCwiY2xpZW50X25hbWUiOiJ1bmtub3duIiwieHB2X2Fzc2V0X2lkIjoxNjI5ODYwNDg0MzY5NzM2LCJhc3NldF9hZ2VfZGF5cyI6MTU4LCJ2aV91c2VjYXNlX2lkIjoxMDEyMCwiZHVyYXRpb25fcyI6NiwiYml0cmF0ZSI6MTMxMjgyMiwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=A1kLKuY6ivheRz7ht8Zxsw&_nc_zt=28&oh=00_AfnQC6W8aGwpBZFnUeCEAhSMjP5RJFSAk9ub2R2fJdiitQ&oe=6939D804",
    "audio_download_url": "https://video-iad3-1.xx.fbcdn.net/o1/v/t2/f2/m69/AQN6l20OxAzMw1UOxK7K6LNIT7XnhOKigCYALVHLbE9nb3aInnzmCU7bMReKkoIHv6VjDJer9t6pdRsbgWdaZXWI.mp4?strext=1&_nc_cat=101&_nc_sid=9ca052&_nc_ht=video-iad3-1.xx.fbcdn.net&_nc_ohc=jfRwzgeVHfEQ7kNvwHhq0BJ&efg=eyJ2ZW5jb2RlX3RhZyI6ImRhc2hfbG5faGVhYWNfdmJyM19hdWRpbyIsInZpZGVvX2lkIjoxMjU4Nzc0MzE5Mjc0ODg3LCJvaWxfdXJsZ2VuX2FwcF9pZCI6MCwiY2xpZW50X25hbWUiOiJ1bmtub3duIiwieHB2X2Fzc2V0X2lkIjoxNjI5ODYwNDg0MzY5NzM2LCJhc3NldF9hZ2VfZGF5cyI6MTU4LCJ2aV91c2VjYXNlX2lkIjoxMDEyMCwiZHVyYXRpb25fcyI6NiwiYml0cmF0ZSI6NDY1MDEsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ==&ccb=17-1&_nc_gid=A1kLKuY6ivheRz7ht8Zxsw&_nc_zt=28&oh=00_AflQIJchcVkGOhG1Sq64yS-bYjXYreZViPSahSeEXCWA-w&oe=6939DD31",

    "_best_video_format": {
      "id": "1136454548558997v",
      "ext": "mp4",
      "height": 1024
    },
    "_best_audio_format": {
      "id": "1222339949371456a",
      "ext": "m4a",
      "abr": 45.467
    },
    "_raw_info": {
      "id": "1258774319274887",
      "uploader": "TECHSUNIL.ve77",
      "webpage_url": "https://m.facebook.com/watch/?v=1258774319274887&_rdr"
    }
  },
  {
    "url": "https://www.facebook.com/share/v/1D9H5Bwyjg/",
    "title": "3.9M views · 43K reactions | From Trash to Cozy!... #BedroomGlowUp #ExtremeMakeover #DIYMakeover #RenovationProject #CozyBedroom #TrashToTransformation #HomeMakeover #FixerUpper | Kou Yang",
    "duration": 15.189,
    "description": "From Trash to Cozy!...#BedroomGlowUp #ExtremeMakeover #DIYMakeover #RenovationProject #CozyBedroom #TrashToTransformation #HomeMakeover #FixerUpper",
    "thumbnail_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t15.5256-10/595693343_2240565119764666_9186510746279598252_n.jpg?stp=dst-jpg_s960x960_tt6&_nc_cat=1&ccb=1-7&_nc_sid=be8305&_nc_ohc=nVxhmuBICBEQ7kNvwGRpbjO&_nc_oc=Adlqa2sK0_in9SZ9vfXUODGjs9EhjPmWZs3QWMMUuCxM9F7JTF-FGw7iWK5ijLofmK4&_nc_zt=23&_nc_ht=scontent-iad3-1.xx&_nc_gid=GEDpA33URLr9fQXcH4nHIg&oh=00_AflELh-6YV8JeQ28QN886IY9IOW2gBVcMo-EjNMtHG6l7A&oe=6939D22D",

    "video_download_url": "https://video-iad3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQMJ4f2AVB7Oajrso6Ki3Eb7tXA-U-uc9b8xmaCAP9xG_KGNmqWjNUYj6l7M7X9s4BLV7fcaToa5Sf2NBN2W5IBhgUSx0Aj8vuOEYho.mp4?_nc_cat=109&_nc_sid=9ca052&_nc_ht=video-iad3-1.xx.fbcdn.net&_nc_ohc=vWREt6ypzhAQ7kNvwG4ZCrT&efg=eyJ2ZW5jb2RlX3RhZyI6ImRhc2hfcjJhdjEtcjFnZW4ydnA5X3E5MCIsInZpZGVvX2lkIjo3ODY2NTA2NDEwODY3NzgsIm9pbF91cmxnZW5fYXBwX2lkIjowLCJjbGllbnRfbmFtZSI6InVua25vd24iLCJ4cHZfYXNzZXRfaWQiOjg2Mzk1NDM5OTUwMjA0NywiYXNzZXRfYWdlX2RheXMiOjAsInZpX3VzZWNhc2VfaWQiOjEwMTIzLCJkdXJhdGlvbl9zIjoxNSwiYml0cmF0ZSI6MzIyODMwMSwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=GEDpA33URLr9fQXcH4nHIg&_nc_zt=28&oh=00_AfkhgfLBOI5b2PgFXbucWkX3dWknFmkZaD2ynkX7YaBzJA&oe=6939C0F2",
    "audio_download_url": "https://video-iad3-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQPPzvSpAKtdNLaOWA59DcS-C39BtZxjDTmw62m2iV7Zh8j2fc0j_2LtrwoVrPIwvNt2U74UlfTiqdTRQiBI06sPvQ8uLVhrltfFxlU.mp4?_nc_cat=1&_nc_sid=9ca052&_nc_ht=video-iad3-1.xx.fbcdn.net&_nc_ohc=q9qJUvRqF4AQ7kNvwHf6Geo&efg=eyJ2ZW5jb2RlX3RhZyI6ImRhc2hfbG5faGVhYWNfdmJyM19hdWRpbyIsInZpZGVvX2lkIjo3ODY2NTA2NDEwODY3NzgsIm9pbF91cmxnZW5fYXBwX2lkIjowLCJjbGllbnRfbmFtZSI6InVua25vd24iLCJ4cHZfYXNzZXRfaWQiOjg2Mzk1NDM5OTUwMjA0NywiYXNzZXRfYWdlX2RheXMiOjAsInZpX3VzZWNhc2VfaWQiOjEwMTIzLCJkdXJhdGlvbl9zIjoxNSwiYml0cmF0ZSI6NzE4NzgsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ==&ccb=17-1&_nc_gid=GEDpA33URLr9fQXcH4nHIg&_nc_zt=28&oh=00_Afk3HVgIUoxkLrnay-zaGvxxRL69w3xdt4a5grbLNTNRbg&oe=6939B545",

    "_best_video_format": {
      "id": "1568408721027848v",
      "ext": "mp4",
      "height": 1800
    },
    "_best_audio_format": {
      "id": "860463746737086a",
      "ext": "m4a",
      "abr": 71.377
    },
    "_raw_info": {
      "id": "786650641086778",
      "uploader": "Kou Yang",
      "webpage_url": "https://m.facebook.com/watch/?v=786650641086778&_rdr"
    }
  }
]

• The actor logs:

  • start/stop lifecycle messages,
  • per-URL processing steps, and
  • extraction errors (per-item error field is also pushed to dataset).

---

Troubleshooting

1. No startUrls provided — Ensure your INPUT.json contains startUrls (array of strings or objects with url).
2. Extraction fails for a specific URL — The actor will push an object containing an error field for that URL; inspect the dataset row for the error message.
3. Dependency / import errors — Confirm required Python dependencies are installed and that you run the script with the correct Python interpreter. Use pip install -r requirements.txt and re-run.

---

Limitations

• The actor extracts metadata and direct stream URLs only; it does not download or merge media streams.
• Selection of “best” formats is heuristic (based on resolution / bitrate / filesize); results may vary depending on available remote formats.
• No explicit CPU/memory hints are provided in input; large batches may require increased resource limits when running at scale.

---