Facebook Scraper: Page Posts & Ads Library

Scraping is asynchronous: submit a run → poll status → fetch data. See the end-to-end flow in Quick Start; the shared response envelope, run state machine, billing, and error codes are in Auth & Error Handling. This page only lists each Facebook endpoint's submit path, target fields, and output fields.

Endpoint Overview

Common headers:

Authorization: Bearer ants_xxxxxxxxxxxx
Content-Type: application/json

The submit body is always { "deliveryMode": "async", "recordLimit": 1000, "targets": [ … ] }: recordLimit caps records per target, and each element in targets uses the fields listed per endpoint below.

💡 You can also use deliveryMode: "sync" (small jobs block until terminal, auto fallback to polling on timeout) — see quick-start · Sync mode.

Page Posts

Scrape posts from one or more Facebook pages, including body text, timestamp, engagement, attachments, and comments.

Endpoint: POST /v1/scraper/facebook/page-posts

Target fields (each element of targets[]):

The posts-per-page cap can also be controlled by the top-level recordLimit in the submit body (see Quick Start).

Output fields (each record in records):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/facebook/page-posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "pageUrls": "[\"https://facebook.com/nike\"]", "since": "2026-01-01", "includeComments": true, "commentsLimit": 20 },
      { "pageIds": "[\"15087023444\"]" }
    ]
  }'

A successful submit returns HTTP 201 + the run id, with status set to queued:

{ "code": 0, "message": "ok", "data": { "id": 1287346, "status": "queued" } }

Then poll GET /v1/scraper/runs/{id} by id until succeeded, and fetch records or download — see the full poll/fetch flow in Quick Start.

Ads Library

Search ads currently or previously served in the Facebook Ads Library, filtered by keyword, country/region, type, and more. One target = one search.

Endpoint: POST /v1/scraper/facebook/ads-library

Target fields (each element of targets[] = one search):

countries is required (at least one country code) to scope the search; search_terms / ad_type and others are optional filters. The number of ads returned is capped by the top-level recordLimit in the submit body.

Output fields (each record in records):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/facebook/ads-library" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      {
        "countries": ["US", "GB"],
        "search_terms": ["nike"],
        "ad_type": "ALL",
        "active_status": "active",
        "start_date": "2026-05-01",
        "end_date": "2026-06-30"
      }
    ]
  }'

A successful submit returns HTTP 201 + the run id, with status set to queued:

{ "code": 0, "message": "ok", "data": { "id": 1287347, "status": "queued" } }

Then poll GET /v1/scraper/runs/{id} by id until succeeded, and fetch records or download — see Quick Start.

Fetching Data & Errors

• Fetch: once the run reaches succeeded, page through records with GET /v1/scraper/runs/{id}/records?page=1&pageSize=20, or download the full result with GET /v1/scraper/runs/{id}/download?format=json|csv|excel.
• Progress & per-target results: poll the run object's targetsOk / targetsFailed for progress; a single page/search failing does not fail the whole run — details are in tasks[].errorMessage.
• Billing: settled by the number of successfully produced records; if every target fails, the hold is released and nothing is charged.
• Errors: request-level errors return the matching HTTP status code + { "code": <int>, "message": <msg> } (e.g. insufficient credits 402, rate limit 429 + Retry-After).

For the envelope, state machine, billing, and full error-code table, see Auth & Error Handling.

FAQ

Q: Can I scrape multiple pages at once?

Yes. targets is an array — a single run can hold multiple searches, and a single target's pageUrls / pageIds can itself carry multiple pages. Per-target status is in the run object's tasks[].

Q: Why don't I get the posts/ads data straight back after submitting?

Scraping is asynchronous: submit to get a run id, it runs in the background, then poll id until succeeded and fetch records or download by id.

Q: Which fields are required for an Ads Library search?

countries is required (at least one country code) to scope the search; search_terms / ad_type and others are optional filters.

Q: Am I charged for failed scrapes?

No. If every target fails, the hold is released and nothing is charged; partial success is billed only for the records actually produced. See Auth & Error Handling.

Next Steps

• Platform guides: TikTok · X · Instagram · LinkedIn · Google · YouTube · Amazon
• Synchronous search: Google SERP
• Auth & Error Handling — Unified envelope, run state machine, billing & error codes