# Social Fetch API - Facebook endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

16 documented Facebook operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/facebook/profiles
Get Facebook profile
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/profiles/get.mdx
SDK: client.facebook.getProfile({ url, includeBusinessHours? })
Parameters:
- url (required, string) - Facebook public profile or page URL to look up.
- includeBusinessHours (optional, boolean) - Optional: include structured business hours in the response when available.
Outcome field: `data.lookupStatus` in `found`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/profiles?url=https://www.facebook.com/profile.php?id=61575098504636" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/profiles/posts
List Facebook profile posts
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/profiles/posts/get.mdx
SDK: client.facebook.getProfilePosts({ url?, pageId?, cursor? })
Parameters:
- url (optional, string) - Full public Facebook profile or page URL.
- pageId (optional, string) - Facebook page or profile id when you have it instead of a full URL.
- cursor (optional, string) - Opaque pagination cursor from a previous response (`data.page.nextCursor`).
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Empty results: An empty `data.posts` page with `hasMore: false` can represent no public posts, restricted visibility, or an unresolvable URL or id—there is no `lookupStatus` field on this route.
Disambiguation: Call `GET /v1/facebook/profiles` first when you need `found` / `private` / `not_found` before interpreting an empty posts page.
curl "https://api.socialfetch.dev/v1/facebook/profiles/posts?url=https://www.facebook.com/profile.php?id=61575098504636" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/profiles/reels
List Facebook profile reels
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/profiles/reels/get.mdx
SDK: client.facebook.getProfileReels({ url })
Parameters:
- url (required, string) - Public Facebook profile or page URL whose reels should be listed.
- cursor (optional, string) - Opaque pagination cursor from a previous response (`data.page.nextCursor`).
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/profiles/reels?url=https://www.facebook.com/profile.php?id=61575098504636" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/profiles/photos
List Facebook profile photos
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/profiles/photos/get.mdx
SDK: client.facebook.getProfilePhotos({ url })
Parameters:
- url (required, string) - Public Facebook profile or page URL whose photos should be listed.
- cursor (optional, string) - Opaque pagination cursor from a previous response (`data.page.nextCursor`).
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/profiles/photos?url=https://www.facebook.com/profile.php?id=61575098504636" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/posts
Get Facebook post or reel
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/posts/get.mdx
SDK: client.facebook.getPost({ url })
Parameters:
- url (required, string) - Public permalink to the Facebook post or reel.
- includeComments (optional) - When true, includes a sample of top-level comments when available.
- includeTranscript (optional) - When true, includes a plain-text transcript when available for the video.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/posts?url=https://www.facebook.com/uniladmag/posts/pfbid02h8QyMzZrMtHks9iU7oneNe4yTKMzNPynvA9WYMedK7eLjU422HD6u3dfmvmgT5QQl" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/posts/comments
List Facebook post or reel comments
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/posts/comments/get.mdx
SDK: client.facebook.getPostComments({ url })
Parameters:
- url (optional, string) - Link to the Facebook post or reel whose comments should be listed.
- cursor (optional, string) - Opaque cursor from a previous response to fetch the next page.
- feedbackId (optional, string) - Optional Facebook feedback identifier for the target post; when available it can improve lookup performance.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/posts/comments?url=https://www.facebook.com/uniladmag/posts/pfbid02h8QyMzZrMtHks9iU7oneNe4yTKMzNPynvA9WYMedK7eLjU422HD6u3dfmvmgT5QQl" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/posts/comments/replies
List Facebook comment replies
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/posts/comments/replies/get.mdx
SDK: client.facebook.getPostCommentReplies({ cursor: comment.repliesCursor })
Parameters:
- cursor (required, string) - Comment `repliesCursor` from post comments, or `page.nextCursor` to paginate replies.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/facebook/posts/comments/replies?cursor=eyJmIjoiWm1WbFpHSmhZMms2WlhoaGJYQnNZWEJmWlhoaGJYQnNZWEIiLCJlIjoiTWpveE56YzROak0xTURNM09tVjRZVzF3YkdWZmRHOXJaVzQ9In0" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/posts/transcript
Get Facebook post transcript
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/posts/transcript/get.mdx
SDK: client.facebook.getPostTranscript({ url })
Parameters:
- url (required, string) - Link to the Facebook post or reel whose transcript should be returned.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `lookup_failed`
curl "https://api.socialfetch.dev/v1/facebook/posts/transcript?url=https://www.facebook.com/uniladmag/posts/pfbid02h8QyMzZrMtHks9iU7oneNe4yTKMzNPynvA9WYMedK7eLjU422HD6u3dfmvmgT5QQl" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/groups/posts
List Facebook group posts
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/groups/posts/get.mdx
SDK: client.facebook.listGroupPosts({ url, sortBy?, cursor? })
Parameters:
- url (required, string) - Public Facebook group URL whose posts should be listed.
- sortBy (optional, string, enum: top | recentActivity | chronological | chronologicalListings) - Optional sort order for the returned posts.
- cursor (optional, string) - Opaque pagination cursor from a previous response (`data.page.nextCursor`).
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Empty results: `lookupStatus: not_found` often means the group URL was wrong or unresolved. Each page bills separately, including `not_found` outcomes.
Disambiguation: Pass a full Facebook group URL (`facebook.com/groups/{id-or-slug}/…`), not a profile or page URL. Use `sortBy: chronological` for general feeds; use `chronologicalListings` for Buy/Sell marketplace groups. Upstream returns a small number of posts per page (often around three). No server-side keyword filter — filter client-side on `text` after fetching pages.
curl "https://api.socialfetch.dev/v1/facebook/groups/posts?url=https://www.facebook.com/groups/rateplate" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/marketplace/items
Get Facebook Marketplace item
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/marketplace/items/get.mdx
SDK: client.facebook.getMarketplaceItem({ itemId: "1656586118821988" })
Parameters:
- itemId (optional, string) - Facebook Marketplace item identifier. Provide this instead of url when you already know the item id.
- url (optional, string) - Public Facebook Marketplace item URL.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/marketplace/items?itemId=abc123" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/marketplace/locations/search
Search Facebook Marketplace locations
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/marketplace/locations/search/get.mdx
SDK: client.facebook.searchMarketplaceLocations({ query: "Austin" })
Parameters:
- query (required, string) - City or place name to search for Facebook Marketplace locations.
curl "https://api.socialfetch.dev/v1/facebook/marketplace/locations/search?query=Austin" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/marketplace/search
Search Facebook Marketplace listings
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/marketplace/search/get.mdx
SDK: client.facebook.searchMarketplace({ query: "bike", lat: 30.2677, lng: -97.7475 })
Parameters:
- query (required, string) - Search query text for marketplace listings.
- lat (required) - Latitude for the marketplace search location.
- lng (required) - Longitude for the marketplace search location.
- radiusKm (optional) - Optional search radius in kilometers.
- minPrice (optional) - Optional minimum listing price.
- maxPrice (optional) - Optional maximum listing price.
- count (optional) - Optional number of listings to return.
- sortBy (optional, string, enum: suggested | distanceAscend | creationTimeDescend | priceAscend | priceDescend) - Optional sort order for marketplace listings.
- deliveryMethod (optional, string, enum: all | localPickup | shipping) - Optional delivery method filter for marketplace listings.
- condition (optional, string, enum: new | usedLikeNew | usedGood | usedFair) - Optional item condition filter for marketplace listings.
- dateListed (optional, string, enum: 1 | 7 | 30 | all | last24Hours | last7Days | last30Days) - Optional date-listed filter for marketplace listings.
- availability (optional, string, enum: available | sold | all) - Optional availability filter for marketplace listings.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/facebook/marketplace/search?query=bike&lat=30.2677&lng=-97.7475" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/ad-library/ads
Get Facebook Ad Library ad
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/ad-library/ads/get.mdx
SDK: client.facebook.getAdLibraryAd({ adId: "902134546059754", includeTranscript: true })
Parameters:
- adId (optional, string) - Facebook Ad Library archive id for the ad.
- url (optional, string) - Public Facebook Ad Library URL for the ad.
- includeTranscript (optional) - When true, includes a plain-text transcript when available for the ad video.
- trim (optional) - When true, requests a smaller payload before normalization.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/ad-library/ads?adId=abc123&includeTranscript=value" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/ad-library/ads/search
Search Facebook Ad Library ads
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/ad-library/ads/search/get.mdx
SDK: client.facebook.searchAdLibraryAds({ query: "running", mediaType: "video" })
Parameters:
- query (required, string) - Search query text for Facebook Ad Library ads.
- sortBy (optional, string, enum: impressions | most-recent) - Optional sort order for returned ads.
- searchType (optional, string, enum: keyword-unordered | exact-phrase) - Optional keyword matching mode for the search query.
- adType (optional, string, enum: all | political-and-issue) - Optional filter for all ads or political and issue ads.
- country (optional, string) - Optional country code filter. Use ALL to search all countries.
- status (optional, string, enum: all | active | inactive) - Optional ad status filter.
- mediaType (optional, string, enum: all | image | video | meme | image-and-meme | none) - Optional creative media filter.
- startDate (optional, string) - Optional start date filter in YYYY-MM-DD format.
- endDate (optional, string) - Optional end date filter in YYYY-MM-DD format.
- cursor (optional, string) - Opaque pagination cursor from a previous response.
- trim (optional, boolean) - When true, returns a smaller response with fewer fields.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/facebook/ad-library/ads/search?query=value" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/ad-library/companies/ads
List Facebook company ads
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/ad-library/companies/ads/get.mdx
SDK: client.facebook.listCompanyAds({ pageId: '367152833370567' })
Parameters:
- pageId (optional, string) - Facebook page id when you have it instead of a company name.
- companyName (optional, string) - Company or page name to search when you do not have a page id.
- country (optional, string) - Optional country code filter. Use ALL to search all countries.
- status (optional, string, enum: all | active | inactive) - Optional ad status filter.
- mediaType (optional, string, enum: all | image | video | meme | image-and-meme | none) - Optional creative media filter.
- language (optional, string) - Optional language code filter.
- sortBy (optional, string, enum: impressions | most-recent) - Optional sort order for returned ads.
- startDate (optional, string) - Optional start date filter in YYYY-MM-DD format.
- endDate (optional, string) - Optional end date filter in YYYY-MM-DD format.
- cursor (optional, string) - Opaque pagination cursor from a previous response (`data.page.nextCursor`).
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/facebook/ad-library/companies/ads?pageId=abc123" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/facebook/ad-library/companies/search
Search Facebook ad library companies
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/facebook/ad-library/companies/search/get.mdx
SDK: client.facebook.searchAdLibraryCompanies({ query: "nike" })
Parameters:
- query (required, string) - Search query text for Facebook ad library companies.
curl "https://api.socialfetch.dev/v1/facebook/ad-library/companies/search?query=value" \
  -H "x-api-key: YOUR_API_KEY"