Specialty extractors

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.

Markdown agents.txt

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.

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.

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: 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 without submitting the search again.

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

{
  "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:

{
  "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.

{
  "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.

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.