Facebook Profile Posts API
Latest posts and Reels from a Facebook page — listingHits / timings.phase; 60s deadline, failures 0 credits.
GET request to /v1/facebook/profile-posts that responds with clean JSON and costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh. Start with 100 free credits — no credit card.What is the Facebook Profile Posts API?
Pass a Facebook page URL or @handle and get that page's recent posts as clean JSON (text posts and Reels mixed). author.username uses one consistent vanity casing across the page (no nasa vs NASA split). engagement always includes views and shares (null when unknown / not a video) — never invents shares:0 from listing noise. The envelope names the yield: requested, totalReturned, listingHits, hydrateFailures, hydrateSkipped, hasMore, truncatedReason=listing-window | hydrate-budget | deadline | null (always keyed), timings{listingMs,hydrateMs,phase,totalMs}, and fetchedAt (not a second scrapedAt). When hasMore is false: listingHits − hydrateFailures − hydrateSkipped = totalReturned. When hasMore is true: min(listingHits, requested) − hydrateFailures − hydrateSkipped = totalReturned. The logged-out listing hop is ~23–29s typical and hard-capped at 40s; each permalink hydrate is typically 6–10s (can be ~100ms when listing already carried the post) and is capped at 12s. Hydration is sequential and clock-aware: keep going while elapsed + 12s < 60s (the cap, not the typical 6–10s), then return what fits with truncatedReason=hydrate-budget. If the 60s deadline fires after posts have already finished, those posts ship as a 200 with truncatedReason=deadline instead of a 503 with nothing. limit default 4 / max 4 (422 above that); the cap is the ceiling, not a promise. Listing is capped at 40s. A 503 carries the same timings so phase=listing vs phase=hydrate is readable; phase=listing forces hydrateMs=0. Hard 60s deadline: hang with no posts is 503, empty live page is 502, both 0 credits. A failed page is remembered for 60s so retries are an instant 502/503 with the same timings. Flat 2 credits on the native path.
What you get
- Mixed posts + Reels with one author.username casing per page
- requested / listingHits / hydrateSkipped / truncatedReason / timings / fetchedAt
- 503 timings.phase names listing vs hydrate
- 60s deadline; 502/503 cost 0 credits; 60s negative cache on failure
Try it
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).
Parameters
curl "https://api.captapi.com/v1/facebook/profile-posts?url=https%3A%2F%2Fwww.facebook.com%2FNASA" \
-H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."Edit the parameters and the code updates instantly. Switch languages and hit copy.
Example response
{
"success": true,
"data": {
"url": "https://www.facebook.com/NASA",
"totalReturned": 2,
"posts": [
{
"platform": "facebook",
"url": "https://www.facebook.com/NASA/posts/pfbid0TBwRTPkxfaLhYBjfsK1xApVksSVHddNrpqUqcqNsKxVvKjqT6dAG8HnxWGA3odp5l",
"id": "1587644189397618",
"caption": "This is messy 😬\n \nA galaxy cluster is exactly what you'd think: a bunch of galaxies grouped together. This galaxy cluster is made of two sub-clusters with similar mass, locked in a messy process of interacting and separating. Eventually, they'll merge. Though their relationship is… complicated, it helps us study the region.\n \nThe cluster's extreme and concentrated mass curves light with its gravity. This is called gravitational lensing, and it works like a glass lens bending and focusing light. Objects are magnified and their brightness is enhanced, so if they lie in exactly the right place, background galaxies and even individual stars that would have been far too faint and distant to spot will be made visible.",
"description": "This is messy 😬\n \nA galaxy cluster is exactly what you'd think: a bunch of galaxies grouped together. This galaxy cluster is made of two sub-clusters with similar mass, locked in a messy process of interacting and separating. Eventually, they'll merge. Though their relationship is… complicated, it helps us study the region.\n \nThe cluster's extreme and concentrated mass curves light with its gravity. This is called gravitational lensing, and it works like a glass lens bending and focusing light. Objects are magnified and their brightness is enhanced, so if they lie in exactly the right place, background galaxies and even individual stars that would have been far too faint and distant to spot will be made visible.",
"publishedAt": "2026-07-27T15:33:07.000Z",
"thumbnailUrl": "https://scontent-dfw5-2.xx.fbcdn.net/v/t39.99422-6/758964186_1384158170473704_9008748322111971488_n.png?stp=dst-jpg_tt6&cstp=mx2047x1012&ctp=s1080x2048&_nc_cat=1&ccb=1-7&_nc_sid=12...",
"author": {
"username": "NASA",
"displayName": "NASA - National Aeronautics and Space Administration",
"url": "https://www.facebook.com/NASA"
},
"engagement": {
"likes": 1861,
"comments": 84,
"views": null,
"shares": null
},
"isVideo": false
},
{
"platform": "facebook",
"url": "https://www.facebook.com/reel/1380134307388381",
"id": "1584419709720066",
"caption": "During his eight months aboard the International Space Station, NASA astronaut Chris Williams conducted numerous experiments to improve life on Earth and prepare us for missions to the Moon and Mars.\n\nFrom cancer research to advancing technology, read about Williams’ work during his first time in space: https://go.nasa.gov/3RavGXj",
"description": "During his eight months aboard the International Space Station, NASA astronaut Chris Williams conducted numerous experiments to improve life on Earth and prepare us for missions to the Moon and Mars.\n\nFrom cancer research to advancing technology, read about Williams’ work during his first time in space: https://go.nasa.gov/3RavGXj",
"publishedAt": "2026-07-23T16:31:54.000Z",
"durationSeconds": 112.946,
"thumbnailUrl": "https://scontent-sea5-1.xx.fbcdn.net/v/t15.5256-10/754970839_803020196231197_5928609298551288000_n.jpg?stp=dst-jpg_tt6&cstp=mx720x405&ctp=s720x405&_nc_cat=102&ccb=1-7&_nc_sid=be830...",
"videoUrl": "https://video-sea1-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQNNFuni8clCeMB5VeV07ZDIzXWkhBI5ozM_78otCALjoD72HsRW7yvnWXM_b0WGcKAjPk-KGDhCqRkGsaoZ57noEirZQ7LpYHZZbTVu3jMMQg.mp4?_nc_cat=106&_nc...",
"author": {
"username": "NASA",
"displayName": "NASA - National Aeronautics and Space Administration",
"url": "https://www.facebook.com/NASA",
"profileImage": "https://scontent-sea5-1.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=108&ccb=1-7&_nc_sid=2d3e12&...",
"verified": true
},
"engagement": {
"views": 411000,
"likes": 5594,
"comments": 170,
"shares": 240
},
"isVideo": true,
"link": "https://go.nasa.gov/3RavGXj"
}
],
"scrapedAt": "2026-08-03T11:00:00Z"
}
}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:
Top-level fields
urlFacebook page URL you queried.totalReturnedPosts in this response (length of posts[]).scrapedAtWhen this response was collected (ISO 8601). Envelope-level freshness on listings that expose it (e.g. Facebook profile-reels) — not a per-row stamp on Spotify search. facebook/profile-posts uses fetchedAt; there is no scrapedAt twin.
Posts
Each item in posts contains:
platformPlatform identifier for this response (matches the endpoint's platform).urlFacebook page URL you queried.idId of this posts item.captionPost or creative caption when the platform exposes one.descriptionDescription of this posts item.publishedAtPublish date (ISO 8601) when the platform exposes an absolute timestamp.thumbnailUrlThumbnail image URL.authorAuthor name or handle.engagementEngagement metrics for the item.isVideoWhether the item is a video.
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 4, max 4). The logged-out listing hop is ~23–29s typical, hard-capped at 40s. Each hydrate is typically 6–10s (can be ~100ms when listing already carried the post) and is capped at 12s. The next-item fit check uses that 12s cap, not the typical 6–10s, so a call cannot exceed 60s. The loop stops when the next item would miss the 60s deadline and returns what it has (truncatedReason=hydrate-budget | deadline). Asking for 20 cannot return 20 inside that ceiling. 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. |
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.
facebook_profile_posts via @captapi/mcp. Set it up →How it works
- 1. Sign up — get 100 free credits, no card required.
- 2. Create a key from your dashboard.
- 3. Send one request to
/v1/facebook/profile-postsand parse the JSON response.
Use cases
Content Pipelines
Ingest a channel's catalog in bulk.
Monitoring
Detect new uploads automatically.
Archiving
Snapshot a creator's library — metadata plus CDN media URLs (re-fetch before mediaUrlsExpireAt).
Analytics
Aggregate performance across many videos.
Frequently asked questions
What does the Facebook Profile Posts API do?+
The Facebook Profile Posts API lets you list items in bulk with metadata from a public Facebook post using one GET request to /v1/facebook/profile-posts. It returns clean JSON — no OAuth or infrastructure setup required.
How many credits does the Facebook Profile Posts 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 proxies, rate limits, retries, and authentication for you.
Why did I get 1 post when I asked for 20?+
limit max is 4 — 20 is a 422. requested is a cap, not a promise. truncatedReason is always keyed (listing-window | hydrate-budget | deadline | null). When hasMore is false: listingHits − hydrateFailures − hydrateSkipped = totalReturned. When hasMore is true: min(listingHits, requested) − hydrateFailures − hydrateSkipped = totalReturned. listingHits is how many distinct posts the logged-out HTML window held — on a large page that is often 1–3. hydrateSkipped were found but not hydrated because the next item would have missed the 60s deadline (NASA: 3 of 4, hydrate-budget). That thin window is expected from logged-out Facebook, not a silent miss.
What is the deadline, and why did retries take another 42 seconds?+
Hard ceiling 60s (503 on hang with no posts, 502 when a live page yields nothing). Failures are 0 credits. A failed page is remembered for 60s so the next retry is an instant 502/503 with the same timings — the failure is cached, never data. The listing hop is ~23–29s typical and hard-capped at 40s — a 40 001 ms 503 is that cap, not a 53 s listing the docs used to quote from a failed call. Hydrates are typically 6–10s (sometimes ~100ms when listing already carried the post), sequential, and capped at 12s; the loop returns what fits (hydrate-budget) and finished posts still ship if the deadline fires (deadline).
Why did I get a 503 with no posts?+
Read timings.phase. phase=listing means the logged-out HTML hop never returned (hard-capped at 40s) — hydrateMs is 0 on that path. phase=hydrate means listing finished and a detail fetch overran. listingMs + hydrateMs is never greater than totalMs. If posts had already finished when the deadline fired, they ship as a 200 with truncatedReason=deadline instead of a 503 with nothing.
Where is scrapedAt?+
Removed. Use envelope fetchedAt. There is no scrapedAt twin — same as group-posts. Do not compare profile-posts to profile-reels by a shared scrapedAt; the two pages fetch independently.
Why is limit max 4?+
A hydrate is typically 6–10s (sometimes ~100ms when listing already carried the post) and the listing hop is ~23–29s typical, hard-capped at 40s. The fit check uses the 12s cap, not the typical, so listing-at-40 plus one hydrate finishes by 52s and a second is not started. limit stays at 4 because the loop is a clock: it hydrates while elapsed + 12s still fits, then returns what it has (hydrate-budget). If the deadline fires after posts finished, those posts still ship (deadline). limit=20 cannot return 20 inside that ceiling. Asking above 4 is a 422 that names the field.
Is the Facebook Profile Posts 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.
More Facebook APIs
Ready to use the Facebook Profile Posts API?
Sign up, grab your key, and make your first call in 60 seconds.