> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Facebook Scraper by ScrapeBadger — Overview

> Facebook Marketplace listings, search, Pages, profiles, Groups, posts, comments and the Ad Library as clean JSON — no Meta developer app, App Review or access token required.

## Scraper API for Facebook

The ScrapeBadger **Facebook API** turns `facebook.com` into a clean JSON feed:
**Marketplace** listings, global search across seven tabs, Page and profile
detail, Group metadata and feeds, post and comment threads, and the public
**Ad Library**.

<Info>
  All endpoints are `GET`, live under `https://scrapebadger.com/v1/facebook/*`,
  and authenticate with the `X-API-Key` header. Credits are charged per request
  (see the table below) and reported on the `X-Credits-Used` response header.
</Info>

<Warning>
  **Global keyword Search** (`/search`, `/search/pages`, `/search/people`,
  `/search/groups`, `/search/posts`, `/search/places`, `/search/events`) is
  **temporarily unavailable** while we expand capacity and currently returns
  `503 {"error": "temporarily_unavailable"}`. Everything else — Marketplace,
  Pages, profiles, Groups, posts, comments and the Ad Library — is live.
</Warning>

<Note>
  Facebook's own Graph API exposes **no Marketplace inventory at any price**,
  and reading Pages, Groups or posts through Graph requires an owned asset plus
  an approved permission. This API needs none of that — no Meta developer app,
  no App Review, no OAuth tokens.
</Note>

## Features

* **Marketplace search** — the headline surface. Keyword search across the
  largest classifieds inventory in the world, with filters for price range,
  age of listing, condition, delivery method and sort order. Returns
  `price_amount` + `currency`, geo coordinates, photo galleries, condition
  subtitles, `is_sold` / `is_pending` state and the seller actor.
* **Marketplace category browse** — walk a whole vertical (`vehicles`,
  `propertyrentals`, `electronics`, `apparel`, …) in one location, with the
  same price and sort filters.
* **Marketplace item detail** — the full listing: description body, complete
  `photos[]` gallery, vertical-specific `attributes` (vehicle make/model/
  mileage, property beds/baths) and seller profile.
* **Search across seven tabs** — one mixed `all` tab plus `pages`, `people`,
  `groups`, `posts`, `places` and `events`. Every result carries a `type`, an
  id and a canonical URL you can hand straight to a detail endpoint.
* **Pages & profiles** — name, category, verification, cover photo, follower /
  like counts, and the About tile (website, phone, email, address, rating),
  plus paginated timelines.
* **Groups** — privacy, member count, description, creation date, and the
  group feed with full post objects.
* **Posts & comments** — a single post by numeric id, `pfbid` string,
  `permalink.php` form or reel URL, with attachments, reaction breakdown
  (`top_reactions[]`), share and comment counts — and the comment thread with
  author, reactions and reply counts.
* **Ad Library** — competitive-intelligence search over Facebook's public ad
  archive: creative copy, snapshot URL, flight dates, `publisher_platforms[]`,
  images/videos and the CTA — plus advertiser Page search, Page transparency
  info (owner, admin countries, history, political ad spend) and EU DSA
  transparency (reach and demographics) on ad lookups with an EU `country`.

## Markets

Marketplace is **location-scoped** by slug and the Ad Library is
**country-scoped** by ISO code. Search, Pages, Groups and posts are global and
need no market parameter.

| Surface | Parameter | Default | Catalog |
| - | - | - | - |
| Marketplace | `location` | `nyc` | [`/marketplace/locations`](/api-reference/endpoint/facebook/marketplace-category) — `nyc`, `la`, `chicago`, `houston`, `seattle`, `sanfrancisco`, `miami`, `atlanta`, `london`, `toronto`, `sydney` (any city slug works) |
| Ad Library | `country` | `US` | Any ISO 3166-1 alpha-2 code |
| Search / Pages / Groups / Posts | — | global | — |

## Credits

| Endpoint | Path | Credits |
| - | - | - |
| Marketplace search | `GET /v1/facebook/marketplace/search` | 5 |
| Marketplace category | `GET /v1/facebook/marketplace/category/{category}` | 5 |
| Marketplace item | `GET /v1/facebook/marketplace/item/{item_id}` | 5 |
| Marketplace locations | `GET /v1/facebook/marketplace/locations` | 0 |
| Marketplace categories | `GET /v1/facebook/marketplace/categories` | 0 |
| Search (all tabs) | `GET /v1/facebook/search` · `/search/{tab}` | 5 |
| Get Page / profile | `GET /v1/facebook/pages/{identifier}` · `/profiles/{identifier}` | 5 |
| Page / profile posts | `GET /v1/facebook/pages/{identifier}/posts` · `/profiles/{identifier}/posts` | 5 |
| Get group | `GET /v1/facebook/groups/{group_id}` | 5 |
| Group posts | `GET /v1/facebook/groups/{group_id}/posts` | 5 |
| Get post | `GET /v1/facebook/posts/{post_id}` | 5 |
| Post comments | `GET /v1/facebook/posts/{post_id}/comments` | 10 |
| Ad Library search | `GET /v1/facebook/ads/search` | 5 |
| Get ad | `GET /v1/facebook/ads/{ad_archive_id}` | 5 |
| Ad Library page search | `GET /v1/facebook/ads/pages/search` | 5 |
| Ad Library page info | `GET /v1/facebook/ads/pages/{page_id}` | 5 |

## Quickstart

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://scrapebadger.com/v1/facebook/marketplace/search?query=macbook%20pro&location=nyc&max_price=1200" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    "https://scrapebadger.com/v1/facebook/marketplace/search?" +
      new URLSearchParams({
        query: "macbook pro",
        location: "nyc",
        max_price: "1200",
      }),
    { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } },
  );
  const data = await res.json();
  console.log(data.listings.length, "listings");
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://scrapebadger.com/v1/facebook/marketplace/search",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={
          "query": "macbook pro",
          "location": "nyc",
          "max_price": 1200,
      },
  )
  print(len(res.json()["listings"]), "listings")
  ```
</CodeGroup>

## Pagination

Every list endpoint uses Facebook's Relay **cursor** pagination — there are no
page numbers. Read `end_cursor` from the response and pass it back as the
`after` query parameter while `has_next_page` is `true`.

```python Python theme={null}
cursor, page = None, 0
while True:
    res = requests.get(
        "https://scrapebadger.com/v1/facebook/marketplace/search",
        headers={"X-API-Key": "YOUR_API_KEY"},
        params={"query": "macbook pro", "location": "nyc", "after": cursor},
    ).json()
    print(page, len(res["listings"]))
    if not res["has_next_page"]:
        break
    cursor, page = res["end_cursor"], page + 1
```

## Timestamps

Every datetime ships in **both** forms: `*_utc` (Unix seconds, e.g.
`creation_time_utc`) and `*_at` (ISO 8601 UTC string, e.g. `created_at`).

<Tip>
  Start from [`/marketplace/search`](/api-reference/endpoint/facebook/marketplace-search)
  or [`/search`](/api-reference/endpoint/facebook/search) to discover entities,
  then take the returned `id` / `url` into
  [`/marketplace/item/{item_id}`](/api-reference/endpoint/facebook/marketplace-item),
  [`/pages/{identifier}`](/api-reference/endpoint/facebook/get-page) or
  [`/groups/{group_id}`](/api-reference/endpoint/facebook/get-group) for full
  detail — search results are deliberately shallow discovery records.
</Tip>

***

*ScrapeBadger is an independent tool and is not affiliated with, endorsed by, or sponsored by Facebook or Meta. "Facebook" is a trademark of Meta Platforms, Inc., used here only to describe the platform this scraper is designed to work with.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.