Facebook Profile Photos API

What is the Facebook Profile Photos API?

Pass a Facebook Page URL or @handle and get photos from the public /photos grid as clean JSON: id, url, image (full-size CDN), width/height (always keyed; null when Facebook omits them), and accessibilityCaption — Facebook's image alt-text, not a user-written post caption. Publish time and likes/comments are usually absent on this surface (platform limit, not a Captapi gap). Facebook does not expose a separate thumbnail on this grid — image is the delivered CDN URL. limit (default 20, max 200) is your cap; the /photos SSR grid is a single batch (often ~8). Every 200 includes limit, totalReturned, retrievableCount (unique Photo nodes in this batch), hasMore, and nextCursor (always null — a missing cursor key is a bug; null is the end). hasMore is true only when we sliced below the batch. truncatedReason=photos-grid-batch when the grid bound you — not "the Page only has 8" and not "limit was ignored." Flat 2 credits. Pass cache=true for the 24h shared cache.

What you get

• accessibilityCaption = alt-text (never mislabeled as caption)
• Full-size image URL (no thumbnailUrl on this surface)
• Honest: date/engagement usually unavailable on /photos
• limit / retrievableCount / hasMore / nextCursor — which limit bit you

Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).

curl "https://api.captapi.com/v1/facebook/profile-photos?url=https%3A%2F%2Fwww.facebook.com%2FNASA" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

Example response

{
  "success": true,
  "data": {
    "url": "https://www.facebook.com/NASA",
    "totalReturned": 2,
    "photos": [
      {
        "platform": "facebook",
        "id": "1587644152730955",
        "url": "https://www.facebook.com/photo.php?fbid=1587644152730955",
        "image": "https://scontent-dfw6-2.xx.fbcdn.net/v/t39.99422-6/758964186_1384158170473704_9008748322111971488_n.png?stp=dst-jpg_tt6&cstp=mx2047x1012&ctp=s2047x1012&_nc_cat=1&ccb=1-7&_nc_sid=12...",
        "width": 2047,
        "height": 1012,
        "accessibilityCaption": "A galaxy cluster in deep space. It is filled with elliptical galaxies: small, bright white glowing ovals. The two largest elliptical galaxies, left and right of center, are bright cores that radiate light. Unrelated, distant galaxies are scattered around as red smudges and dots. Many of these are stretched out into red arcs and lines by the galaxy cluster’s strong gravity, creating multiple images in places. Numerous spiral galaxies and bright stars appear in the foreground. Credit: ESA/Webb, NASA & CSA, S. Fujimoto"
      },
      {
        "platform": "facebook",
        "id": "1586655189496518",
        "url": "https://www.facebook.com/photo.php?fbid=1586655189496518",
        "image": "https://scontent-dfw6-2.xx.fbcdn.net/v/t39.30808-6/756229023_1586655192829851_1923291187225748989_n.jpg?stp=dst-jpg_tt6&cstp=mx1884x1054&ctp=s1884x1054&_nc_cat=110&ccb=1-7&_nc_sid=...",
        "width": 1884,
        "height": 1054,
        "accessibilityCaption": "An aerial view of a spacecraft about to land on Earth; the capsule is barely visible, but a large white-and-red parachute billows above it. The plain around it is flat and featureless. Credit: NASA+"
      }
    ]
  }
}

Billing metadata is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Source. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.

Response structure

A successful call returns success and a data object with the following fields:

Parameters

Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh.

How it works

1. 1. Sign up — get 100 free credits, no card required.
2. 2. Create a key from your dashboard.
3. 3. Send one request to /v1/facebook/profile-photos and parse the JSON response.

Use cases

Frequently asked questions

More Facebook APIs