Facebook Video Downloader API

Turn public Facebook video, Reel, Watch, and share links into direct Facebook video and audio URLs, multiple available qualities, and structured metadata. Process up to 100 URLs per run with one result per unique input.

Use this Actor as a Facebook Video Downloader API, Facebook Reel Downloader, Facebook Watch video resolver, or bulk Facebook video metadata API. Each successful item includes a recommended media URL and can also include separate audio, representative video formats, thumbnails, creator information, timing, and engagement statistics when Facebook exposes them.

Video files are not stored. The Actor returns temporary media URLs that should be consumed soon after the run finishes. It does not download, transcode, or merge media files.

Key features

• Direct Facebook video and audio URLs — receive media URLs that can be used immediately in your own downloader, workflow, or application.
• Multiple video qualities — request the recommended result or inspect representative SD, HD, and higher-resolution formats when available.
• Up to 100 URLs per run — resolve a single Reel or process a batch while preserving one isolated result for every unique input.
• Video and audio stream awareness — distinguish progressive video, video-only streams, separate audio, and formats that require muxing.
• Automation-ready output — get predictable Dataset items with success status, public error codes, canonical URLs, and nullable fields.
• Best-effort Facebook metadata — collect title, description, thumbnail, author, duration, publication time, and statistics when available.
• Optional proxy support — use the standard Apify Proxy configuration when direct requests are blocked or rate-limited.

Quick start

Resolve one Facebook Reel

1. Open the Actor in Apify Console.
2. Add a public Facebook Reel or video URL.
3. Keep quality set to best and run the Actor.
4. Open the Dataset and use videoUrl, audioUrl, or formats.

{
    "videoUrls": ["https://www.facebook.com/reel/123456789/"],
    "quality": "best",
    "includeAudio": true,
    "includeAllFormats": true,
    "includeMetadata": true
}

Resolve a batch

{
    "videoUrls": [
        "https://www.facebook.com/reel/123456789/",
        "https://www.facebook.com/watch/?v=987654321",
        "https://fb.watch/example/"
    ],
    "quality": "hd",
    "includeAudio": true,
    "includeAllFormats": true,
    "includeMetadata": true,
    "maxConcurrency": 5,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
}

Exact duplicate strings are processed once in first-seen order. An invalid or unavailable item does not stop the rest of the batch.

Supported Facebook URLs

The Actor supports public content only and recognizes the following URL structures:

Content	Example URL	Notes
Facebook Reel	https://www.facebook.com/reel/{videoId}/	Numeric Reel ID
Facebook video page	https://www.facebook.com/{username}/videos/{videoId}/	Numeric video ID
Facebook Watch	https://www.facebook.com/watch/?v={videoId}	Numeric v parameter
Reel share link	https://www.facebook.com/share/r/{shareId}/	Redirect is resolved during processing
Video share link	https://www.facebook.com/share/v/{shareId}/	Redirect is resolved during processing
Short Watch link	https://fb.watch/{shortId}/	Short link is resolved during processing
Mobile or web Facebook host	https://m.facebook.com/reel/{videoId}/	Supported when the path matches one of the structures above

The accepted Facebook hosts are facebook.com and its subdomains, including www.facebook.com, m.facebook.com, and web.facebook.com, plus fb.watch. Common tracking parameters are removed during normalization.

Private, friend-only, group-private, deleted, login-only, age-restricted, and region-restricted videos may not resolve. General profile, post, photo, group, page, and feed URLs are not treated as video inputs unless their URL matches a supported video structure.

Input

Field	Type	Default	Description
videoUrls	string[]	Required	Between 1 and 100 Facebook video URLs. Values are trimmed; exact duplicates are processed once in first-seen order.
quality	best, hd, sd, or audio	best	Controls the recommended top-level media selection. See the behavior details below.
includeAudio	boolean	true	Includes a separate audio URL and audio formats when available. It does not remove audio already embedded in a progressive video.
includeAllFormats	boolean	true	When true, returns representative detected formats for the target video. When false, returns only the recommended video and audio formats.
includeMetadata	boolean	true	Attempts to return title, description, thumbnail, author, timing, and engagement data. Metadata is best effort.
maxConcurrency	integer	5	Number of input URLs processed at the same time. Minimum 1; maximum 10. Lower it if requests are being rate-limited.
proxyConfiguration	object	{ "useApifyProxy": false }	Optional standard Apify Proxy configuration. Direct connections are used by default.

Quality behavior

• best recommends the best detected video with embedded audio first, then considers resolution and bitrate. This can select a lower-resolution progressive stream instead of a higher-resolution video-only stream.
• hd prefers a detected stream at 720p or higher, prioritizing one with embedded audio when available.
• sd prefers a detected stream at 480p or lower, prioritizing one with embedded audio when available.
• audio requests audio-oriented use, but the output still preserves the best detected videoUrl. Use audioUrl or an item in formats where type is audio for the separate audio stream.

Quality preferences cannot create a format that Facebook does not expose. The actual quality value in the result describes the selected video, such as 720p, or is audio when only audio was resolved.

Metadata behavior

Metadata is optional and can be incomplete even when media resolution succeeds. title and description can be null, and Facebook pages sometimes expose generic interface labels instead of a human-authored title. Treat videoUrl, audioUrl, and formats as the core media fields; do not use metadata alone to determine success.

Output

The Actor writes one result per input to the default Dataset. A successful item requires at least one usable video or audio URL.

Core success example

{
    "inputUrl": "https://www.facebook.com/reel/123456789/",
    "status": "success",
    "contentType": "reel",
    "videoUrl": "https://video.example.net/video-720.mp4",
    "audioUrl": null,
    "quality": "720p",
    "hasAudio": true,
    "requiresMuxing": false,
    "formats": [
        {
            "formatId": "progressive-720",
            "type": "video",
            "quality": "720p",
            "width": 1280,
            "height": 720,
            "bitrate": 1800000,
            "mimeType": "video/mp4",
            "extension": "mp4",
            "hasVideo": true,
            "hasAudio": true,
            "requiresMuxing": false,
            "url": "https://video.example.net/video-720.mp4"
        }
    ],
    "errorCode": null,
    "errorMessage": null,
    "processedAt": "2026-08-05T05:00:00.000Z"
}

Unavailable values are returned as null, not as empty strings or artificial zeroes. formats is always an array and is empty for a failed item.

Understanding video, audio, and muxing

Facebook can expose the same video as several different media representations:

• Progressive video contains both video and audio in one URL. It has type: "video", hasAudio: true, and requiresMuxing: false.
• Video-only stream contains the picture without sound. It has type: "video", hasAudio: false, and requiresMuxing: true.
• Audio-only stream contains sound without video. It has type: "audio", hasVideo: false, and its URL can also appear as the top-level audioUrl.

High-resolution formats, including some 1080p representations, are often video-only. If the recommended videoUrl has requiresMuxing: true, combine it with audioUrl in your own downstream tool to create one file with sound. Muxing may be required, and the Actor reports that requirement but does not perform the merge.

Because best prioritizes a complete stream with embedded audio, the recommended videoUrl may be a lower-resolution progressive version. If maximum picture quality matters more, inspect formats, choose the desired video-only representation, and pair it with the separate audio representation.

Example format list:

[
    {
        "formatId": "dash-video-1080",
        "type": "video",
        "quality": "1080p",
        "width": 1920,
        "height": 1080,
        "bitrate": 3200000,
        "mimeType": "video/mp4",
        "extension": "mp4",
        "hasVideo": true,
        "hasAudio": false,
        "requiresMuxing": true,
        "url": "https://video.example.net/video-1080.mp4"
    },
    {
        "formatId": "dash-audio-128",
        "type": "audio",
        "quality": "audio",
        "width": null,
        "height": null,
        "bitrate": 128000,
        "mimeType": "audio/mp4",
        "extension": "m4a",
        "hasVideo": false,
        "hasAudio": true,
        "requiresMuxing": false,
        "url": "https://video.example.net/audio-128.m4a"
    },
    {
        "formatId": "progressive-720",
        "type": "video",
        "quality": "720p",
        "width": 1280,
        "height": 720,
        "bitrate": 1800000,
        "mimeType": "video/mp4",
        "extension": "mp4",
        "hasVideo": true,
        "hasAudio": true,
        "requiresMuxing": false,
        "url": "https://video.example.net/video-720.mp4"
    }
]

When includeAllFormats is true, the list contains representative formats detected for the target video. Related or recommended Facebook videos are excluded, and equivalent encodes with the same media characteristics are reduced to one representative entry. Availability and technical details vary by video.

Output field reference

Identity and processing state

Field	Type	Nullable	Description
inputUrl	string	No	Trimmed URL supplied in the input.
canonicalUrl	string	Yes	Canonical or resolved Facebook content URL.
platform	string	No	Always facebook.
contentType	string	Yes	reel, video, watch, share, or unknown.
videoId	string	Yes	Detected numeric Facebook video ID when available. Share links may not expose it.
status	string	No	success or failed.
errorCode	string	Yes	Stable public error code for failed items; null on success.
errorMessage	string	Yes	Human-readable public failure description; null on success.
processedAt	string	No	ISO 8601 timestamp indicating when the item was processed.

Recommended media

Field	Type	Nullable	Description
videoUrl	string	Yes	Recommended direct video URL. Can be null when only audio is available.
audioUrl	string	Yes	Best separate audio URL when requested and available.
quality	string	Yes	Selected video quality label, such as 1080p or 720p; audio when only audio is selected.
hasAudio	boolean	Yes	Whether the selected videoUrl contains embedded audio. null when no video is selected or the property cannot be determined.
requiresMuxing	boolean	Yes	Whether the selected video needs separate audio to produce a single file with sound.

Metadata

Field	Type	Nullable	Unit or meaning
title	string	Yes	Best-effort page title; can contain a generic Facebook interface label.
description	string	Yes	Best-effort page description; can be generic or absent.
thumbnailUrl	string	Yes	Direct thumbnail or preview image URL.
duration	number	Yes	Video duration in seconds.
createTime	number	Yes	Publication time as a Unix timestamp in seconds.
createTimeIso	string	Yes	Publication time in ISO 8601 format.

Author object

Field	Type	Nullable	Description
author.id	string	Yes	Facebook author or page ID when available.
author.name	string	Yes	Author or page name.
author.profileUrl	string	Yes	Author or page profile URL.
author.avatarUrl	string	Yes	Author or page avatar URL.

The author object is present in the standard result shape, but any of its fields can be null.

Statistics object

Field	Type	Nullable	Unit or meaning
statistics.playCount	number	Yes	Reported play or view count.
statistics.likeCount	number	Yes	Reported like count.
statistics.reactionCount	number	Yes	Reported reaction count.
statistics.commentCount	number	Yes	Reported comment count.
statistics.shareCount	number	Yes	Reported share count.

The statistics object is present in the standard result shape. Counts are best effort and can be null; they are not replaced with zero when unavailable.

Format object

Field	Type	Nullable	Unit or meaning
formats[].formatId	string	No	Identifier unique within the result item.
formats[].type	string	No	video or audio.
formats[].quality	string	Yes	Quality label such as 1080p, 720p, or audio.
formats[].width	number	Yes	Video width in pixels.
formats[].height	number	Yes	Video height in pixels.
formats[].bitrate	number	Yes	Approximate bitrate in bits per second.
formats[].mimeType	string	Yes	Media MIME type, for example video/mp4.
formats[].extension	string	Yes	Suggested file extension, for example mp4 or m4a.
formats[].hasVideo	boolean	No	Whether the representation contains video.
formats[].hasAudio	boolean	Yes	Whether the representation contains audio; null when unknown.
formats[].requiresMuxing	boolean	No	Whether this representation needs a separate audio stream for a combined file.
formats[].url	string	No	Direct temporary media URL.

API examples

The Actor slug is lance_api/facebook-video-downloader-api. Replace only YOUR_APIFY_TOKEN with your Apify API token.

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('lance_api/facebook-video-downloader-api').call({
    videoUrls: ['https://www.facebook.com/reel/123456789/', 'https://www.facebook.com/watch/?v=987654321'],
    quality: 'best',
    includeAudio: true,
    includeAllFormats: true,
    includeMetadata: true,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
    console.log({
        status: item.status,
        videoUrl: item.videoUrl,
        audioUrl: item.audioUrl,
        formats: item.formats,
    });
}

Python

from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')

run = client.actor('lance_api/facebook-video-downloader-api').call(run_input={
    'videoUrls': ['https://www.facebook.com/reel/123456789/'],
    'quality': 'best',
    'includeAudio': True,
    'includeAllFormats': True,
    'includeMetadata': True,
})

items = client.dataset(run['defaultDatasetId']).list_items().items
for item in items:
    print({
        'status': item['status'],
        'videoUrl': item.get('videoUrl'),
        'audioUrl': item.get('audioUrl'),
        'formats': item['formats'],
    })

cURL

This synchronous endpoint returns Dataset items directly when the run finishes within the request timeout:

curl -X POST \
  "https://api.apify.com/v2/acts/lance_api~facebook-video-downloader-api/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrls": ["https://www.facebook.com/reel/123456789/"],
    "quality": "best",
    "includeAudio": true,
    "includeAllFormats": true,
    "includeMetadata": true
  }'

Each returned object contains the top-level videoUrl and audioUrl, plus the formats array when enabled.

Pricing

This Actor uses pay-per-result pricing. Free-plan users pay $0.005 per successful result, equivalent to $5.00 per 1,000 successful results. Apify paid membership tiers receive progressively lower prices: Bronze users pay $0.0045 per result ($4.50 per 1,000), Silver users pay $0.0040 per result ($4.00 per 1,000), and Gold users receive the lowest price of $0.0035 per result, or $3.50 per 1,000 successful results.

You are charged once for each unique input that successfully returns at least one usable video or audio URL. Failed inputs are not charged. Exact duplicate URLs in the same run are processed only once, so they are not charged repeatedly. A result containing several qualities or entries in formats is still one result and creates only one charge—there is no separate charge for each format, video URL, audio URL, or metadata field.

Apify Proxy costs

Apify Proxy is optional and is not included in the per-result prices above. If you enable Apify Proxy through proxyConfiguration, any proxy usage is billed separately by Apify according to your Apify plan, selected proxy type, and actual usage. Proxy charges do not come from this Actor and do not change the number of successful results charged by the Actor. Review the current proxy allowances and rates on the official Apify pricing page before enabling it.

Common use cases

• Build a Facebook Reel Downloader or Facebook Watch video downloader workflow.
• Resolve a Facebook MP4 download URL for authorized content.
• Collect representative Facebook video formats and qualities for media processing.
• Extract a separate Facebook audio URL for an authorized audio workflow.
• Enrich a CMS, catalog, or internal tool with public Facebook video metadata.
• Process up to 100 public Facebook video links in a bulk automation.
• Feed direct media URLs into storage, moderation, editing, or transcription systems you operate.
• Integrate Facebook video resolution into an API backend, no-code workflow, or AI agent.

AI Agent integration

The Actor can be called through the Apify MCP server from compatible AI clients that support MCP tools. After connecting Apify MCP and authorizing your account, an agent can run lance_api/facebook-video-downloader-api and read its Dataset results.

Example agent prompt:

Run lance_api/facebook-video-downloader-api for this public Facebook Reel URL.
Return the status, recommended videoUrl, separate audioUrl, quality,
requiresMuxing, and the available formats. Do not expose my Apify token.

Direct API integration is usually preferable when your application needs deterministic batch processing or tighter control over retries and result storage.

Common errors

Each failure is written as a Dataset item with status: "failed", a public errorCode, and an errorMessage.

Error code	Meaning and suggested action
INVALID_URL	The input is not a valid HTTP or HTTPS URL. Check the value and protocol.
UNSUPPORTED_URL	The URL is not a recognized Facebook video structure. Use a supported Reel, video, Watch, share, or fb.watch URL.
VIDEO_UNAVAILABLE	The video could not be resolved. It may be deleted, private, restricted, temporarily unavailable, or affected by a transient Facebook response. Retry later if the content is known to be public.
LOGIN_REQUIRED	Facebook requires authentication. The Actor supports public content and does not log in.
PRIVATE_OR_RESTRICTED	The content is private or restricted and cannot be accessed publicly.
FACEBOOK_BLOCKED	Facebook rejected the request. Retry later or use a suitable proxy configuration.
RATE_LIMITED	Requests were rate-limited. Reduce maxConcurrency, retry later, or use a suitable proxy.
MEDIA_NOT_FOUND	The page resolved, but no usable video or audio representation was detected.
REQUEST_TIMEOUT	The per-item processing deadline expired. Retry later or lower concurrency.
PROXY_ERROR	The selected proxy configuration could not be used. Check the configuration and account access.
INTERNAL_ERROR	An unexpected processing error occurred. Retry once, then contact support with the Run ID if it repeats.

FAQ

Does this Actor download or store Facebook video files?

No. Video files are not stored. The Actor resolves direct media URLs and structured data. Your own application can download authorized content from those URLs if needed.

Are the returned media URLs permanent?

No. URLs are temporary signed media links and may expire. Use or download them soon after the run completes rather than saving them as permanent references.

Does every videoUrl include sound?

No. Check hasAudio and requiresMuxing. A progressive stream includes sound; a high-resolution video-only stream may need the separate audioUrl.

Why can the recommended video be lower quality than a format in formats?

The best selection prioritizes a complete stream with embedded audio. A higher-resolution format may be video-only. Choose it from formats and mux it with audioUrl if maximum resolution is more important.

Does the Actor merge video and audio?

No. It identifies separate streams and sets requiresMuxing, but it does not merge or transcode media. Muxing may be required in your downstream workflow.

Can it resolve private or login-only Facebook videos?

No. The Actor supports public content only and does not accept cookies, log in to Facebook, or bypass access controls.

Why are title, description, or statistics missing or generic?

Facebook does not consistently expose complete metadata on every public page. Some pages return generic interface labels. These fields are best effort and can be null even when media resolution succeeds.

Why did the same public share link work once and fail later?

Facebook share redirects, signed resources, availability checks, blocking, and rate limits can vary between requests. Retry later, reduce concurrency, or use an appropriate proxy. A previous success does not make the direct URL permanent.

Can I process many links in one run?

Yes. Supply up to 100 URLs per run. The Actor writes one isolated item for every unique input, so one failure does not cancel the remaining items.

Does includeAllFormats return videos from the related-content feed?

It is designed to return representative formats associated with the requested target video and to exclude related or recommended videos. Because Facebook can change its page data, verify media identity in critical workflows and report repeatable mismatches with a Run ID.

Does each format create an additional charge?

No. One unique input that resolves successfully is charged as one result, regardless of how many video qualities, audio streams, or entries are returned in formats. Exact duplicate inputs in the same run are processed and charged only once, and failed inputs are not charged.

Limitations and public-content notice

• Public content only: private, restricted, deleted, login-only, and inaccessible videos are not supported.
• Direct media and thumbnail URLs are temporary and can expire.
• Available resolutions, audio layout, MIME types, and metadata differ between videos.
• High-resolution video can be video-only and require a separate audio stream.
• Facebook page structures and access behavior change over time, so the same URL can occasionally produce a transient failure.
• The Actor does not expand profiles, pages, feeds, or collections into multiple videos.
• The Actor does not download, store, transcode, merge, subtitle, comment, or transcribe content.

Responsible use

Use this Actor only for public content that you are authorized to access and process. Respect Facebook's terms, copyright, privacy, data-protection requirements, and all applicable laws. Do not use it to bypass authentication, access controls, or content restrictions.

Support

If a repeatable problem occurs, open an issue on the Actor page or email lanceapi2026@hotmail.com.

To help diagnose the problem, include:

• the Apify Run ID;
• a non-sensitive public example URL;
• the relevant input options, excluding credentials;
• status, errorCode, and errorMessage;
• the result you expected.

Do not send your Apify token, cookies, login credentials, or private Facebook links.