---
title: Specialty extractors
description: Extract structured data from supported sites without writing selectors.
---

Specialty extractors provide source-specific inputs and structured results. They reuse API authentication, jobs, billing and result polling. Facebook uses the browser engine; Google Ads uses plain HTTP.

## Facebook Ads Library

`POST /extract/facebook-ads-library` or MCP `extract_facebook_ads` collects ads from a Facebook Ads Library search URL. It reads embedded structured data, then captures additional batches while the browser loads more results. No selectors, actions or Meta API token are required.

```bash
curl -X POST 'https://api.scrapesilo.com/extract/facebook-ads-library?wait=false' \
  -H 'Authorization: Bearer sf_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&q=wellaray.com&search_type=keyword_unordered",
    "limit": 60,
    "useProxy": "us"
  }'
```

This uses browser pricing: **5 credits for one submitted URL**, including pagination within that job. A request accepts one URL. The browser's ad blocking is disabled for this extractor.

### Parameters

| Parameter | Default | Meaning |
|---|---|---|
| `url` | Required | An HTTPS `facebook.com/ads/library/` or `www.facebook.com/ads/library/` URL. Search filters come from its query string. |
| `limit` | `100` | Maximum unique ads to return, from 1 to 1,000. |
| `useProxy` | Off | Existing proxy option: `true` or a two-letter country code. |
| `sessionId` | Omitted | An existing saved browser session belonging to your API key. |
| `options.timeoutMs` | `90000` | Total browser execution budget, up to 120,000 milliseconds. |

Existing `myProxyUrl`, `myProxyConfig`, `options.headless` and `options.resolution` are also supported. For a custom proxy, set `useProxy: true` alongside its configuration. See [browser options](/docs/engines).

Proxy use is explicit. Facebook may rate-limit the direct connection or a proxy; a proxy does not guarantee complete collection. The proxy country controls the connection's exit location, while the URL's `country` filter controls the requested ad search.

### Jobs and results

The route uses the same responses as [scrape endpoints](/docs/api/scrape): HTTP 200 returns a result array; `wait=false` or a wait deadline returns HTTP 202 with jobs and `X-Scrape-Job-Ids`. Poll [the existing job result endpoint](/docs/api/jobs) without submitting the search again.

Each completed result has the usual `url`, `jobId`, response diagnostics and `data.extraction`:

```json
{
  "ads": [],
  "collectedCount": 0,
  "reportedCount": 0,
  "hasNextPage": false,
  "complete": true,
  "stopReason": "exhausted"
}
```

The example is an exhausted search with no ads. Each populated `ads` entry contains `id`, `pageId`, `pageName`, `isActive`, `startTime`, `endTime`, `platforms`, `displayFormat`, `body`, `title`, `caption`, `linkUrl`, `cta`, `images`, `videos` and `cards`. Times are the source's Unix timestamps in seconds. Missing scalar values are `null`; missing collections are empty arrays. Every carousel card and available image/video variant is retained. Ads are deduplicated by ID, not by creative text or advertiser.

### Completeness

`complete: true` means Facebook explicitly indicated that no next page remains and all collected ads fit within your limit. `reportedCount` is Facebook's reported search count; it can change during collection and need not equal the number of unique records returned.

| Stop reason | What happened |
|---|---|
| `exhausted` | Facebook indicated the end of the results. |
| `limit` | The requested maximum was reached. |
| `rate_limited` | Facebook rejected a request with its rate-limit error, even if HTTP status was 200. |
| `blocked` | A captured request received an HTTP error. |
| `timeout` | The collection budget ended. |
| `stalled` | Collection made no progress for 15 seconds. |
| `source_error` | A response was unreadable, invalid, rejected or exceeded capture bounds. |

Partial collections keep the ads already collected with `complete: false`. If no recognizable results were obtained at all, the job fails instead of returning a misleading empty success. Inspect both the normal job error and extraction completeness.

The extractor collects what the website exposes. It does not promise access to all worldwide ads, private metrics or data unavailable in your search. It does not use Meta's official Ad Library API, which has different coverage.

## Use through the browser action DSL

The specialty route compiles to an ordinary browser scrape. Advanced API or MCP clients can use the same registered action through `/scrape/browser` or `scrape_browser`:

```json
{
  "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&q=wellaray.com&search_type=keyword_unordered",
  "useProxy": "us",
  "options": { "blockAds": false, "timeoutMs": 90000, "waitFor": "domcontentloaded" },
  "actions": {
    "extraction": { "fn": "facebook-ads-library", "args": { "limit": 60 } }
  }
}
```

For the legacy `scrape` MCP tool, add `"engine": "browser"`. This is a browser-only action; HTML extraction cannot paginate the library.

## Google Ads by website

Use `POST /extract/google-ads-library` or MCP `extract_google_ads` with a domain. Discovery runs over HTTP, without a browser, selector DSL, Google credentials, or BigQuery.

```json
{
  "domain": "hyggear.com",
  "platform": "google_search",
  "limit": 100
}
```

| Input | Behavior |
|---|---|
| `domain` | Required website domain or HTTP(S) URL; normalized to its hostname |
| `platform` | Optional: `google_play`, `google_maps`, `google_search`, `youtube`, `google_shopping`. Omit for all platforms |
| `adFormat` | Optional: `text`, `image`, `video`; independent of platform |
| `limit` | Default 100; 1–1,000 ads, collected in pages of up to 100 |
| `options.timeoutMs` | Total discovery and preview budget; default 90,000, maximum 120,000 |
| HTTP transport | Existing headers, proxy and saved-session fields; custom headers/cookies are not forwarded to preview hosts |

To request YouTube video creatives, supply both `"platform": "youtube"` and `"adFormat": "video"`. A YouTube placement can contain text or image ads. The former separate `extract_youtube_ads_library` tool is replaced by this single tool; former `platform: "search"` becomes `"google_search"`, and former `"all"` becomes an omitted platform.

The existing JSON queue owns authentication, job history, concurrency, billing (**1 credit/job**) and polling. REST `?wait=false` or MCP `wait: false` returns jobs; poll those IDs without resubmitting.

### Creative content

Results under `data.extraction` contain `domain`, optional `platform`/`adFormat`, `ads`, `collectedCount`, `hasNextPage`, `complete`, `stopReason`, `creativesAvailable`, and `creativesComplete`.

Each ad includes advertiser/creative IDs, advertiser name, matching domain, format, creative-page URL, first/last discovery timestamps, a preview reference when present, and available text/image/video URLs. Dates are discovery timestamps, not a BQ statistical reporting window. Headline, description, CTA, channel, and destination URL are nullable.

- **Search:** returns content/image URLs already present in discovery. No additional creative lookup, preview fetch, image download, or OCR.
- **Video on other platforms or unfiltered searches:** fetches the representative script preview over HTTP and parses embedded data for YouTube URLs and copy. It does not execute scripts or fetch every creative variation.
- **Image/text on other platforms or unfiltered searches:** keeps usable discovery content as-is. If content is missing and a supported preview is supplied, fetches it over HTTP for the main image URL and available headline, body and CTA. It does not substitute a logo for the ad image.

`previewUrl` can reference a script or iframe; it is not necessarily an image URL. `imageUrls` contains image references. Missing preview content is explicit through `creativeStatus: "unavailable"`. `creativeSource` identifies `inline` or `http_preview` extraction. No OCR, transcription, media download, or BigQuery enrichment is performed.

`complete` concerns discovery pagination. `creativesComplete` means every returned ad has usable representative content; it does **not** mean all variations were extracted. Preview failures preserve discovered ads. Blocked, malformed, repeated-cursor or timeout responses produce explicit failure/partial status rather than claiming an exhaustive result. Ambiguous empty upstream responses fail instead of asserting that no ads exist.

Google's underlying endpoints are undocumented. Coverage and returned preview content can change; successful samples are not a guarantee of uninterrupted access.