How to get Facebook profile photos
GET request to /v1/facebook/profile-photos with your input. You get clean JSON back in seconds for 2 credits per call — no OAuth, scraping or platform SDKs. Photo grid from a Facebook Page — full image URL plus accessibilityCaption (alt-text, not a post caption).How to get Facebook profile photos (step by step)
- 1
Get a free API key
Create a free Captapi account (100 credits, no card) and generate an API key from the dashboard.
- 2
Call the Facebook Profile Photos API
Send an authenticated GET request to /v1/facebook/profile-photos with your input. No OAuth, no scraping setup.
- 3
Read the JSON response
Parse the clean JSON response. Pass cache=true for a free 24h cache hit; default is always fresh.
Code example
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_..."What the response looks like
{
"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 (credits charged, cache hit/miss) is returned in the X-Captapi-Credits and X-Captapi-Cache response headers.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | Facebook profile/page URL, @handle, or page name. The URL platform must match this endpoint's platform. Do not pass cross-platform URLs, e.g. YouTube to TikTok, Instagram to Facebook, LinkedIn to X/Twitter, or Pinterest to Rumble. |
| limit | integer | No | Max items to return (default 20, max 200). The public /photos grid is a single SSR batch (often ~8) — retrievableCount is that batch, not a promise Facebook will fill limit. Flat 2 credits per call. |
| cache | boolean | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. |
Frequently asked questions
What does the Facebook Profile Photos API do?
The Facebook Profile Photos API lets you list items in bulk with metadata from a public Facebook profile photos using one GET request to /v1/facebook/profile-photos. It returns clean JSON — no OAuth or infrastructure setup required.
How many credits does the Facebook Profile Photos API cost?
Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.
Do I need a Facebook API key or OAuth?
No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle access, rate limits, retries, and authentication for you.
Why did I get 8 photos when I set limit=200?
limit is your cap. retrievableCount is how many Photo nodes the public /photos grid yielded this call — a single SSR batch, often ~8. That is not "the Page only has 8 photos" and not "limit was ignored." hasMore is always false and nextCursor always null (no cursor on this surface). truncatedReason=limit means the batch held more than limit — raise limit to get them. truncatedReason=photos-grid-batch means the grid bound you.
Where is thumbnailUrl?
Facebook's /photos grid does not expose a separate thumbnail. image is the delivered CDN URL. width/height are always keyed (null when Facebook omits them). accessibilityCaption is alt-text, not a post caption — date and engagement are usually unavailable on this surface.
Is the Facebook Profile Photos API suitable for production use?
Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.
Ready to get Facebook profile photos?
Start free with 100 credits — no credit card required.
Get your free API key