# Facebook (/docs/facebook)



Facebook [#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/...`

<Callout>
  Reply threads do not take a comment id. 

  `/v1/facebook/post/comment/replies`

   needs the 

  `feedback_id`

   

  **and**

   

  `expansion_token`

   that 

  `/v1/facebook/post/comments`

   returns for that comment. Neither is the comment's own id, and there is no way to construct them — you have to make the parent call first.
</Callout>

Getting started [#getting-started]

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

```bash
# 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 [#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 [#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 [#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
recent posts with reaction, comment and share counts. Posts return a single page and there is no
cursor: Facebook exposes no deeper pagination on public group content, so `sort_by` is the only
lever you have over what comes back.

Events [#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]

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.

```bash
# 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 [#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 [#endpoints]

<PlatformEndpoints platform="facebook" />

Read this before you build [#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 have no second page.** Treat `group/posts` as a sample of the current feed, not as
a crawlable archive.

Notes [#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 [#official-facebook-resources]

* [Facebook Graph API](https://developers.facebook.com/docs/graph-api/) — Official Meta
  developer documentation
* [Meta for Developers](https://developers.facebook.com/) — Meta developer platform