# Facebook API (/api/facebook)

Facebook pages and their posts, reels and events, post comments and transcripts, public groups, Marketplace listings, events and the Meta Ad Library.

## When To Use This API [#when-to-use-this-api]

The Facebook API is for agent workflows that need public, platform-native data without writing a custom collector for every task. Use it when a prompt needs evidence from live public records, when a Skill needs repeatable enrichment, or when product code needs the same contract an agent discovered through MCP.

This section lists 21 live Facebook operations from the canonical OpenAPI spec. Each operation page documents the route, method, parameters, response envelope, pagination behavior when available, and the error vocabulary shared across UnifAPI.

- Pull a public Facebook page's posts, reels, photos, events and comment threads for brand, creator and community research.
- Search the Meta Ad Library by keyword or advertiser and list the ads a page is running for competitive ad intelligence.
- Search Facebook events and Marketplace listings by city or keyword for local demand, pricing and event discovery workflows.

## Agent Contract Notes [#agent-contract-notes]

Agents usually discover these endpoints with the hosted UnifAPI MCP server, inspect the operation schema, then call only the records needed for the current task. Developers can call the same endpoints over HTTP with an API key, which makes the path from exploratory agent run to production integration direct.

Every successful response uses a stable envelope with a request id, data payload, optional pagination cursor, and billing metadata. Errors use the same closed vocabulary across platforms, so retry logic, user-facing explanations, and cost reporting can stay consistent even when a workflow spans multiple public-data sources.

When you are choosing an operation, start from the public identifier the user already has: a profile username, post id, channel id, subreddit name, search term, or URL-derived slug. Prefer the narrowest endpoint that answers the question, then expand only when the agent needs more evidence. This keeps record usage predictable, makes citations easier to explain, and avoids turning a focused research task into an expensive crawl.

## Operations [#operations]

### Ads [#ads]

- [`GET /facebook/ads/{id}`](/api/facebook/ads/id/get) — Get a Facebook Ad Library ad — Returns one ad from the Meta Ad Library by archive id: advertiser, creative, run dates, platforms and, for EU ads, reach and targeting.
- [`GET /facebook/ads/search`](/api/facebook/ads/search/get) — Search Facebook Ad Library ads — Searches the Meta Ad Library by keyword with country, status, media type, language and date filters.

### Advertisers [#advertisers]

- [`GET /facebook/advertisers/{id}/ads`](/api/facebook/advertisers/id/ads/get) — List ads a Facebook Page is running — Returns ads from the Meta Ad Library for one advertiser Page id, with country, status, media type, language and date filters.
- [`GET /facebook/advertisers/search`](/api/facebook/advertisers/search/get) — Search Facebook Ad Library advertisers — Returns Meta Ad Library advertisers whose name matches a query, with Page ids for /facebook/advertisers/{id}/ads.

### Events [#events]

- [`GET /facebook/events/{id}`](/api/facebook/events/id/get) — Get a Facebook event — Returns one public Facebook event by id: schedule, place, hosts, attendance and tickets.
- [`GET /facebook/events/explore`](/api/facebook/events/explore/get) — List Facebook events for a city — Returns public Facebook events for a city from its Facebook Events explore URL, optionally limited to a time window.
- [`GET /facebook/events/search`](/api/facebook/events/search/get) — Search Facebook events — Returns public Facebook events whose name matches a query, with dates, place and attendance.

### Groups [#groups]

- [`GET /facebook/groups/{id}/posts`](/api/facebook/groups/id/posts/get) — List posts in a public Facebook group — Returns posts from a public Facebook group with text, media, author and engagement counts.
- [`GET /facebook/groups/{id}`](/api/facebook/groups/id/get) — Get a public Facebook group — Returns a public Facebook group by id or vanity name: name, description, privacy, member count and activity.

### Marketplace [#marketplace]

- [`GET /facebook/marketplace/items/{id}`](/api/facebook/marketplace/items/id/get) — Get a Facebook Marketplace listing — Returns one Facebook Marketplace listing by item id: price, description, photos, attributes, seller and delivery options.
- [`GET /facebook/marketplace/locations/search`](/api/facebook/marketplace/locations/search/get) — Search Facebook Marketplace locations — Returns Facebook Marketplace locations that match a place name, with the coordinates /facebook/marketplace/search needs.
- [`GET /facebook/marketplace/search`](/api/facebook/marketplace/search/get) — Search Facebook Marketplace listings — Returns Facebook Marketplace listings for a keyword near a latitude and longitude, with price, condition and delivery filters.

### Posts [#posts]

- [`GET /facebook/posts/comments/replies`](/api/facebook/posts/comments/replies/get) — List replies to a Facebook comment — Returns replies to one Facebook comment.
- [`GET /facebook/posts/comments`](/api/facebook/posts/comments/get) — List comments on a Facebook post or Reel — Returns top-level comments on a public Facebook post or Reel by URL.
- [`GET /facebook/posts`](/api/facebook/posts/get) — Get a Facebook post or Reel by URL — Returns one public Facebook post or Reel by its URL: author, text, media, music and reaction, comment and share counts.
- [`GET /facebook/posts/transcript`](/api/facebook/posts/transcript/get) — Get the transcript of a Facebook video post — Returns the spoken-word transcript of a public Facebook video post or Reel by URL, for videos up to a few minutes long.

### Profiles [#profiles]

- [`GET /facebook/profiles/{username}/events`](/api/facebook/profiles/username/events/get) — List events hosted by a Facebook profile or Page — Returns public events hosted by a Facebook profile or Page with dates, place and attendance.
- [`GET /facebook/profiles/{username}/photos`](/api/facebook/profiles/username/photos/get) — List photos from a Facebook profile or Page — Returns public photos from a Facebook profile or Page with image URLs and captions.
- [`GET /facebook/profiles/{username}/posts`](/api/facebook/profiles/username/posts/get) — List posts from a Facebook profile or Page — Returns recent public posts from a Facebook profile or Page with text, media and reaction, comment and share counts.
- [`GET /facebook/profiles/{username}/reels`](/api/facebook/profiles/username/reels/get) — List Reels from a Facebook profile or Page — Returns public Reels from a Facebook profile or Page with captions, play counts and video URLs.
- [`GET /facebook/profiles/{username}`](/api/facebook/profiles/username/get) — Get a Facebook profile or Page — Returns a public Facebook profile or Page by username: name, category, intro, follower and like counts, contact details and business information.