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 always false (the grid has no cursor). truncatedReason=limit when the batch held more photos than limit — raise limit to get them; truncatedReason=photos-grid-batch when the grid bound you — not "the Page only has 8" and not "limit was ignored." Each photo carries mediaUrlsExpireAt for its signed image URL. 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",
    "limit": 20,
    "totalReturned": 2,
    "retrievableCount": 8,
    "hasMore": false,
    "nextCursor": null,
    "photos": [
      {
        "platform": "facebook",
        "id": "1658876725607697",
        "url": "https://www.facebook.com/photo.php?fbid=1658876725607697",
        "image": "https://scontent.fsjp3-1.fna.fbcdn.net/v/t39.99422-6/855339932_1777262476839819_3793054615548579050_n.png?stp=dst-jpg_tt6&cstp=mx1086x1448&ctp=s1086x1448&_nc_cat=1&ccb=1-7&_nc_sid=127cfc&_nc_ohc=Mo3KbE5S4dIQ7kNvwHohzU_&_nc_oc=AdrD3BTuXE677dgmCZIf2Jr8gdQNsGBZVsMdsS0RZxuGLlXqe28jZrG7BSaksGmuzOdGvO1nkkauAkIYzHdOSFUL&_nc_zt=14&_nc_ht=scontent.fsjp3-1.fna&_nc_gid=rBnmALgt2-SVwVwK2KbN4A&_nc_ss=7b289&oh=00_AQMgr1UPohdhfu02qLsKNx9N3112l9O6tLvX9WRb65kZfw&oe=6ADBDFCB",
        "accessibilityCaption": "The exhaust plumes from a SpaceX Falcon rocket are lit up by the Sun, creating a shape that looks like a jellyfish. The plumes are blue and red. There is a fuzzy, faint form below that would make the jellyfish's \"legs\".",
        "width": 1086,
        "height": 1448,
        "mediaUrlsExpireAt": "2026-10-23T22:29:31.000Z"
      },
      {
        "platform": "facebook",
        "id": "1658876718941031",
        "url": "https://www.facebook.com/photo.php?fbid=1658876718941031",
        "image": "https://scontent.fsjp3-1.fna.fbcdn.net/v/t39.99422-6/853004113_4511962015717382_7758999524623865845_n.png?stp=dst-jpg_tt6&cstp=mx1086x1448&ctp=s1086x1448&_nc_cat=1&ccb=1-7&_nc_sid=127cfc&_nc_ohc=bfpnfSJAj7MQ7kNvwEBmT2R&_nc_oc=Adoc5ZA3K14MnEK6suh0v4lYXpNEUVgDeH-qnF3x2ZgsBtqn1_4eojrwTemp246YvzZf5WU001lmxQlgUJ5v8-Sy&_nc_zt=14&_nc_ht=scontent.fsjp3-1.fna&_nc_gid=rBnmALgt2-SVwVwK2KbN4A&_nc_ss=7b289&oh=00_AQMzXJUE1ETk6U_SDrLDIEi-hw1sYewmc9jS6GMAO0c1tg&oe=6ADBFACF",
        "accessibilityCaption": "A close up of jellyfish-shaped exhaust plumes from a SpaceX Falcon rocket against a black sky.",
        "width": 1086,
        "height": 1448,
        "mediaUrlsExpireAt": "2026-10-24T00:24:47.000Z"
      }
    ],
    "truncatedReason": "photos-grid-batch"
  }
}

Billing metadata is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Request-Id (include it when contacting support). Where the response has a source field, it names the path that served the data: native, extended, cache or asr. 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