API documentation

Quick start

1. Sign in and create a named key in API keys.
2. Copy these commands and replace the key and Facebook link.

ORIGIN='https://fbdl.vs8.in'
API_KEY='YOUR_API_KEY'
VIDEO='https://www.facebook.com/reel/123456789012345/'

curl --get "$ORIGIN/api" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "url=$VIDEO"

Keys belong in the Authorization header, never in URLs or public frontend code. The tester keeps a revealed key only in this page’s memory; examples always use a placeholder.

GET /api and POST /api accept one public video, reel, post or photo link at a time. POST accepts JSON or form data up to 4 KiB. Use a video or reel URL, a facebook.com/share/v/… or share/r/… link, a facebook.com/watch?v=… link, or fb.watch/…. Public post and photo links are also accepted, including share/p/…, /name/posts/… and photo.php?fbid=…. Provider support varies by link type. Profile pages, private content, expiring Stories and batch requests are not supported.

Choose the details

Omit include for media links and timestamps. Add details only when needed.

curl --get "$ORIGIN/api" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "url=$VIDEO" \
  --data-urlencode 'include=caption,author'

curl "$ORIGIN/api" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://www.facebook.com/reel/123456789012345/","include":"all"}'

Combine groups with commas or a JSON array. Unknown values return 400. Missing details may require extra providers, with up to two additional seconds for your selected metadata. Some fields may remain unavailable.

Fresh results can be reused for up to two minutes while their media links remain valid. refresh=1, or JSON "refresh":true, skips the metadata cache. A successful refresh or cached response counts as one request.

Read the response

{
  "success": true,
  "data": {
    "thumbnail": "https://fbdl.vs8.in/media/OPAQUE_ID/1/cover.jpg",
    "video_url": "https://fbdl.vs8.in/media/OPAQUE_ID/0/video.mp4",
    "media": [
      {
        "type": "video",
        "url": "https://fbdl.vs8.in/media/OPAQUE_ID/0/video.mp4",
        "download_url": "https://fbdl.vs8.in/media/OPAQUE_ID/0/video.mp4?download=1",
        "filename": "video.mp4",
        "quality": "HD",
        "file_size": 12582912,
        "width": 1280,
        "height": 720
      }
    ],
    "source_url": "https://www.facebook.com/reel/123456789012345/",
    "fetched_at": "2026-09-19T12:00:00.000Z",
    "expires_at": "2026-09-19T12:10:00.000Z"
  },
  "metadata": {
    "requested": [],
    "available": [],
    "missing": [],
    "complete": true
  },
  "cached": false
}

data.media contains downloadable files. video_url is the first video, if present. The IDs above are placeholders.

metadata.requested, available and missing describe your selected groups. complete:true means each selected group has a usable value, not that every field exists.

Save media promptly: links last up to ten minutes and may expire sooner upstream. They support HEAD and byte ranges. Opening a media link does not use another API request.

Provider HTML is converted into structured JSON. The API does not invent missing fields. Media endpoints return file bytes; handled errors return JSON.

Quality and file size

Each item in media can include a reported quality label, file_size in bytes, and width and height in pixels. When only a rounded size is supplied, file_size_text preserves it as text, for example 182.6 MB; the website labels it “Reported size”. These fields are included with media-only requests when available. Missing values are omitted; the website shows “Unavailable” for unreported quality or size.

Different returned qualities have their own media and download links. Choose the file you want in the downloader. Quality labels are provider-reported; dimensions are shown separately when supplied. Rounded size text is never converted to an exact byte count. File sizes are not estimated from duration or quality. A provider may return only one format.

One monthly allowance

The free plan includes 2,000 successful requests per UTC calendar month, shared by the website and all your keys. Failed, rejected and incomplete requests do not use this allowance.

• Free plan: 2 requests per second. Send one URL in each request. Extra requests return 429.
• Success counts once: a successful response counts even when served from cache or some optional metadata is missing.
• In progress: requests reserve available allowance until they finish. Failure releases the reservation.
• Monthly reset: the first day of each month at 00:00 UTC. Your dashboard shows local time.
• API keys: up to five active keys by default, all sharing the same allowance.

There are no separate hourly, daily, yearly or concurrency quotas. An administrator can change your monthly allowance, requests per second and key count, or add requests for a particular month. Changes can start now or be scheduled. Your dashboard and account settings show your current limits. An unlimited monthly allowance does not change request speed unless that is also granted. Existing successful requests still count after a change, including this month’s requests made before the new plan.

Use X-RateLimit-Monthly-Limit, X-RateLimit-Monthly-Remaining and X-RateLimit-Monthly-Reset to track available requests and the next UTC reset, expressed as Unix seconds. Remaining allowance excludes in-progress reservations. X-RateLimit-Limit gives your actual requests-per-second limit: 2 on the free plan, a custom number, or unlimited. X-RateLimit-Window: 1 identifies the one-second rolling window. A limit of 0 means API access is paused; contact the administrator.

On 429, wait for Retry-After seconds; do not send a rapid retry loop. Clearing history or creating another key does not reset usage. View your current allowance in Dashboard.

Handle errors

{
  "success": false,
  "error": "Send no more than 2 requests per second.",
  "code": "rate_limit",
  "retry_after": 1
}

Check the HTTP status, then success, error and code in the JSON. A failed API response does not use monthly allowance. If your connection ends before a response arrives, check History before retrying: the original request may have succeeded.

Infrastructure failures outside the Worker may return a different format. Check content type before parsing JSON.

Keys and request history

Give each integration its own named key. You can reveal, copy or revoke your keys in API keys. Older hash-only keys need your saved value; replace one only if you have lost it.

Each key’s history shows its own requests. Use account history for all keys and website requests, filtered by Successful, Failed, In progress or Incomplete. Key revocation blocks new requests; already-issued media links remain usable until expiry.

History is private. Clearing visible history does not erase retained administrator records or reset successful-request usage. API timestamps are UTC; account pages display your local time.

Notifications contains owner notices and unusual-use alerts. Browser notifications are optional and stop when you sign out. Visible account pages update about every ten seconds. An unusual-volume alert is a signal to review activity, not proof that a key was stolen.