Facebook

Public Facebook data on a plain GET: page profiles and their feeds, post comment trees, reels and photo galleries, group posts, the events directory, Marketplace listings, and the full Facebook Ad Library. Nearly all of it is 1 credit — the Ad Library is 5 and transcripts are 10 — which makes Facebook one of the cheapest platforms here to crawl at volume.

Base URL: /v1/facebook/...

Getting started

Every endpoint is a GET with query parameters and an x-api-key header.

# 1. The page
curl "https://www.socialcrawl.dev/v1/facebook/profile?url=https://www.facebook.com/Meta" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Its recent posts, cursor-paged
curl "https://www.socialcrawl.dev/v1/facebook/profile/posts?url=https://www.facebook.com/Meta" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

The profile response carries a page id. Pass it back as pageId on profile/posts instead of the url and the lookup gets faster, and pageId is also what the Ad Library indexes an advertiser by.

GET /v1/facebook/profile/full?url=… does both calls in one, flat 5 credits, and adds computed analytics — average engagement rate, posting cadence, top post, format mix — over a window of posts (1-100, default 25). The profile still comes back if the posts leg fails, with the post-dependent metrics null. Note that author.following and author.posts_count are always null on Facebook, because the profile upstream does not publish those totals.

Posts and comments

/v1/facebook/post returns one post in full, and it is the only endpoint that carries the reactions breakdown — the split between like, love, haha and the rest, rather than a single total. get_comments=true folds in the first several comments and get_transcript=true folds in a video transcript, so a single call can cover a whole post if you do not need to page.

For the full discussion, post/comments walks the comment list by cursor. Pass feedback_id instead of url when you have one from a prior post call: it is materially faster. That same response is where the feedback_id and expansion_token for each comment come from, and those two together open one reply thread through post/comment/replies.

/v1/facebook/post/transcript returns the spoken words of a video post from Facebook's own captions (10 credits).

Media

/v1/facebook/profile/photos returns a page's gallery — photo id, permalink, full-size image, thumbnail, and the accessibility caption where Facebook generated one. It carries no author, engagement, or publish time per photo, so pass a photo's permalink to post when you need those.

/v1/facebook/profile/reels is the cheap reel list, but its view count is the rounded public figure and it has no likes, comments or shares. /v1/facebook/profile/reels/full merges in exact per-reel engagement. It is metered: it consumes upstream pages of 10 reels and bills 5 credits per page, from 5 up to 25 for a limit=50 walk. If the walk hits its internal time budget the response carries _warnings: ["walk_deadline_reached"], the unfetched pages are refunded, and next_cursor resumes exactly where it stopped.

Groups

/v1/facebook/group is the group identity lookup (name, description, member count, privacy) by url or group_id. /v1/facebook/group/posts takes the same identity and returns that group's posts with reaction, comment and share counts. Facebook serves this feed in slices of 3 to 4 posts, so depth is a cursor walk: send pagination.next_cursor back as cursor and repeat until has_more is false. Each page is 1 credit. sort_by=CHRONOLOGICAL is the setting for keeping a busy group current; the default and TOP_POSTS mix older high-engagement posts into the first pages.

Events

Three entry points into the same event objects. /v1/facebook/events lists what is on in a place, taking the URL of a city's Facebook Events page and an optional time window. /v1/facebook/events/search searches the public directory by keyword — it also returns events that have already happened, so filter on is_past yourself. /v1/facebook/profile/events returns one page's own upcoming and past events. Any listing row can be expanded with /v1/facebook/event/details, by numeric id or event url, for the description, start and end times, host and RSVP counts.

Marketplace

Marketplace search is geographic, not textual: marketplace/search requires query, lat and lng together. Get the coordinates from marketplace/location/search, which turns a city or area name into a lat/lng pair.

# 1. Place name to coordinates
curl "https://www.socialcrawl.dev/v1/facebook/marketplace/location/search?query=Austin" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Listings near those coordinates
curl "https://www.socialcrawl.dev/v1/facebook/marketplace/search?query=bike&lat=30.2672&lng=-97.7431&radius_km=40&max_price=500" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

Filters cover min_price/max_price, condition, delivery_method, date_listed, availability (available, sold, all) and sort_by. De-duplicate on listing id: the ordering shifts between calls, so consecutive cursor pages occasionally repeat an item. /v1/facebook/marketplace/item returns one listing in full by numeric id or Marketplace URL.

Ad Library

Four endpoints, all 5 credits except the transcript. /v1/facebook/adlibrary/search/companies turns an advertiser name into a pageId. /v1/facebook/adlibrary/company/ads then returns everything that page is running, filtered by country, status, media_type, language, and a start_date/end_date impressions window, sorted by impressions or recency. /v1/facebook/adlibrary/search/ads goes the other way and searches ad copy by keyword across every advertiser, with search_type for exact-phrase matching and ad_type to restrict to political and issue ads.

/v1/facebook/adlibrary/ad expands one ad by id or url into its creative, spend, impressions and targeting, and /v1/facebook/adlibrary/ad/transcript returns what a video ad says out loud (10 credits), using Facebook's captions where they exist and transcribing the video where they do not.

Endpoints

24 endpoints available.

Read this before you build

country takes exactly one code. Every Ad Library endpoint that accepts country accepts a single two-letter code, not a list. It defaults to ALL.

Ad Library status defaults to ACTIVE. Historical ads are excluded unless you set status explicitly, which is a common reason a competitor sweep looks emptier than expected.

trim=true on the ad endpoints. Ad Library payloads are large. The trimmed variant carries the same rows with the heavy creative metadata dropped.

Group posts come 3 to 4 at a time. The page size is small by Facebook's design, so a day's worth of a busy group is several cursor pages rather than one call. Budget 1 credit per page and loop on has_more.

Notes

• All endpoints use GET with query parameters
• Authentication via the x-api-key header
• Responses follow the unified SocialCrawl schema
• Multi-photo posts return the full media_urls array, not just the first image
• get_business_hours=true on profile adds a business page's opening hours

Official Facebook Resources

• Facebook Graph API — Official Meta developer documentation
• Meta for Developers — Meta developer platform