# Meta (Facebook & Instagram) Ad Library Scraper (`jaybird/meta-ad-library-scraper`) Actor Scrapes Meta's public Ad Library and returns structured ad data. Four lookup modes (page\_id, page\_url, keyword, batch), opt-in pagination, schema-validated output. - **URL**: https://apify.com/jaybird/meta-ad-library-scraper.md - **Developed by:** [Jaybird Technologies](https://apify.com/jaybird) (community) - **Categories:** Lead generation, Social media - **Stats:** 7 total users, 6 monthly users, 90.6% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.50 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Meta Ad Library Scraper Apify Actor that scrapes Meta's public Ad Library (`facebook.com/ads/library`) and returns structured ad data. Four lookup modes (`page_id`, `page_url`, `keyword`, `batch`), opt-in pagination, schema-validated per-item output. ### Why this actor Meta's official Ad Library API requires app review, identity verification, and is restricted to political/issue/EU ads — unusable for general competitive intelligence on SMB and brand advertisers. The public Ad Library website exposes the same data for all ads, but only via a JS-rendered UI behind a browser challenge. This actor productizes the SSR scrape with the things existing Store actors tend to miss: - **Lifecycle dates** (`start_date`, `end_date`) per creative. - **Honest `page_url` resolution** — keyword-search the handle, then filter results by `page_profile_uri` match. No silent fallback to near-matches. - **Schema-validated output** with a non-silent failure envelope. When Meta drifts, you see `_validation_errors` populated on the item, not a silent null. - **Predictable pagination** with a hard cap and a `truncated_reason` discriminator (`max_ads_cap` vs `run_timeout`). ### Input See `.actor/input_schema.json` for the canonical schema. Summary: | Field | Type | Default | Notes | |---|---|---|---| | `search_mode` | enum | `keyword` | One of `page_id`, `page_url`, `keyword`, `batch`. | | `page_id` | string | — | Required when `search_mode=page_id`. Numeric ID. | | `page_url` | string | — | Required when `search_mode=page_url`. e.g. `https://www.facebook.com/PetsOnBroadway` | | `query` | string | — | Required when `search_mode=keyword`. | | `queries` | string[] | — | Required when `search_mode=batch`. | | `region` | string | `US` | ISO 3166-1 alpha-2 country code. Plumbs into Meta's URL `country=` filter only. | | `active_only` | boolean | `true` | When false, includes stopped ads. | | `media_type` | enum | `all` | `all` / `image` / `video`. | | `max_ads_per_advertiser` | integer | 30 | 1..500. Hard cap. | | `follow_pagination` | boolean | `false` | When true, walks `end_cursor` up to `max_ads_per_advertiser`. | #### Examples **Single advertiser by page ID:** ```json {"search_mode": "page_id", "page_id": "142023025844028"} ```` **By page URL (handle resolution + match filter):** ```json {"search_mode": "page_url", "page_url": "https://www.facebook.com/PetsOnBroadway"} ``` **Keyword search:** ```json {"search_mode": "keyword", "query": "Logical Position"} ``` **Batch (no within-run dedupe — see "Behavior notes" below):** ```json { "search_mode": "batch", "queries": ["nike", "adidas", "puma"], "follow_pagination": true, "max_ads_per_advertiser": 100 } ``` ### Output One dataset item per ad surfaced. Duplicate `ad_archive_id`s ARE possible within a single run when overlapping batch queries surface the same ad — consumers dedupe. ```jsonc { // Identity "ad_archive_id": "1667643404381457", "page_id": "142023025844028", "page_name": "Pets On Broadway", "page_profile_uri": "https://www.facebook.com/PetsOnBroadway/", "page_like_count": 3404, "page_categories": ["Pet Supplies"], // Lifecycle (ISO-8601 UTC date; null if Meta omits) "start_date": "2026-05-04", "end_date": "2026-05-09", "is_active": true, // Creative "display_format": "image", // lowercased: image | video | carousel | dco | unknown "title": "petsonbroadway.com", "caption": "petsonbroadway.com", "body_text": "This May, every purchase of Nulo dog food helps...", "cta_text": "Shop now", "cta_type": "SHOP_NOW", "link_url": "https://petsonbroadway.com/collections/nulo", // Media (image_url = first image; video_url prefers HD over SD) "image_url": "https://...img1.jpg", "video_url": null, "all_image_urls": ["https://...img1.jpg"], "all_video_urls": [], // Provenance "matched_via": "page_id", // page_id | page_url | keyword "query": "142023025844028", // original input value the user submitted "region": "US", "fetched_at": "2026-05-15T21:34:12.345Z" // _validation_errors: present and non-empty IF this item failed validation } ``` #### Per-run summary Written to the run's key-value store as `OUTPUT.json`: ```jsonc { "queries_executed": 3, "advertisers_resolved": 3, "ads_returned": 73, "block_rate": 0.0, "validation_error_rate": 0.0, "aborted": false, "aborted_reason": null, "warnings": [], "advertisers": [ { "query": "nike", "matched_via": "keyword", "page_id": "...", "page_name": "Nike", "total_count": 4321, // Meta's library-wide tally "ads_in_dataset": 30, "has_more": true, "end_cursor": "AbCd...", "source_url": "https://www.facebook.com/ads/library/?...", "truncated_reason": "max_ads_cap" // max_ads_cap | run_timeout | null } ] } ``` ### Behavior notes (read this before integrating) #### 1. Items are NOT deduped within a run If you submit `queries: ["nike", "Nike Inc", "Nike Sportswear"]`, the dataset will include the same `ad_archive_id` once per query that surfaced it (with different `query` field values). This is deliberate — each input query is its own search and bills its own events. Always group by `ad_archive_id` if you want unique creatives. #### 2. Validation failures are pushed with `_validation_errors`, not dropped Every item is validated against the Pydantic schema before push. If validation fails (e.g. Meta dropped a field from SSR), the item is still pushed but with a non-empty `_validation_errors` array. Your code MUST check this field — see the worked example below. #### 3. `page_url` mode never silently returns the wrong advertiser When you submit `page_url: "https://www.facebook.com/somehandle"`, the actor keyword-searches the handle, then filters results to only ads whose `page_profile_uri` matches `/somehandle/` (case-insensitive). If no ads match, you get an empty result with a `warnings[]` entry — NOT a near-match from some unrelated page. #### 4. `start_date` / `end_date` are ISO-8601 dates in UTC Meta inlines them as Unix timestamps; the actor normalizes to `"YYYY-MM-DD"` strings. #### 5. Derived fields are deliberately omitted `days_active`, `image_count`, `video_count`, and ad permalink URLs are NOT emitted. Compute client-side: ```python days_active = (date.fromisoformat(end_date) - date.fromisoformat(start_date)).days if end_date else \ (date.today() - date.fromisoformat(start_date)).days image_count = len(item["all_image_urls"]) video_count = len(item["all_video_urls"]) ad_permalink = f"https://www.facebook.com/ads/library/?id={item['ad_archive_id']}" ``` ### Calling the actor #### Synchronous (small lookups, single page) ```bash curl -X POST "https://api.apify.com/v2/acts/~meta-ad-library-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"search_mode": "page_id", "page_id": "142023025844028"}' ``` Returns the dataset as JSON. Good for one-off lookups under ~30 seconds. #### Asynchronous (batches, pagination) ```bash ## Start the run RUN_ID=$(curl -X POST "https://api.apify.com/v2/acts/~meta-ad-library-scraper/runs?token=$APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"search_mode": "batch", "queries": ["nike", "adidas"], "follow_pagination": true}' \ | jq -r '.data.id') ## Poll until SUCCEEDED, or use webhooks curl "https://api.apify.com/v2/actor-runs/$RUN_ID?token=$APIFY_TOKEN" ## Fetch dataset items curl "https://api.apify.com/v2/actor-runs/$RUN_ID/dataset/items?token=$APIFY_TOKEN" ## Fetch OUTPUT.json from the run's KV store curl "https://api.apify.com/v2/actor-runs/$RUN_ID/key-value-store/records/OUTPUT?token=$APIFY_TOKEN" ``` #### Worked parse-with-`_validation_errors` example ```python import requests resp = requests.get( f"https://api.apify.com/v2/actor-runs/{run_id}/dataset/items", params={"token": APIFY_TOKEN}, ) items = resp.json() good, drifted = [], [] for it in items: if it.get("_validation_errors"): drifted.append(it) else: good.append(it) if drifted: ## _validation_errors populated → Meta SSR may have drifted from the ## actor's declared schema. The items still have best-effort extracted ## data, but consuming them as-if-valid risks downstream type errors. print(f"WARNING: {len(drifted)} of {len(items)} items failed validation") for it in drifted[:3]: print(" errors:", it["_validation_errors"]) ## Use only the validated items downstream. process_ads(good) ``` ### Versioning The actor follows semantic versioning over its **output contract**: - **Major bump** (1.x → 2.x): output field removal, or input-schema breaking change. - **Minor bump** (1.0 → 1.1): output field addition, behavior change with release notes. - **Patch**: bug fixes, internal changes. Soft contract breaks from Meta's side (a field that was always populated suddenly becomes null) do NOT trigger a major bump on their own — they surface via populated `_validation_errors` on affected items. If you parse the dataset strictly, check `_validation_errors`. ### Drift detection The actor declares a dataset schema in `.actor/dataset_schema.json`. Apify validates every pushed item against it at runtime and exposes per-field statistics in the Console (null rates, value distributions). For ongoing surveillance: - An **Apify Schedule** runs the actor nightly against a small batch of monitored advertisers. - **Apify Monitoring** alerts on run failure, low item-count, and per-field null-rate spikes — surfacing Meta-side SSR drift before it becomes a customer complaint. This is configured in the Apify Console (Schedules + Monitoring tabs); no external CI is required for drift detection. GitHub Actions in this repo only runs ruff + unit tests on push. ### Versioned specs and proposals This actor is developed using [OpenSpec](https://github.com/Fission-AI/OpenSpec). The current capability spec lives at `openspec/specs/meta-ad-library-scraper/spec.md` once changes are archived; the v1 proposal is in `openspec/changes/add-meta-ad-library-actor/`. ### License TBD — to be set before public release. # Actor input Schema ## `search_mode` (type: `string`): How to look up ads. page\_id and page\_url target a specific advertiser; keyword and batch use Meta's keyword search. ## `page_id` (type: `string`): Required when search\_mode = page\_id. Numeric ID, e.g. 142023025844028. ## `page_url` (type: `string`): Required when search\_mode = page\_url. e.g. https://www.facebook.com/PetsOnBroadway ## `query` (type: `string`): Required when search\_mode = keyword. Free-text search across all advertisers. ## `queries` (type: `array`): Required when search\_mode = batch. One keyword per line. Each query produces its own search results; overlapping queries are NOT deduplicated within a run. ## `region` (type: `string`): Country to filter Meta's Ad Library results to. Defaults to US. ## `active_only` (type: `boolean`): When true, returns only currently-active ads. When false, includes inactive (stopped) ads. ## `media_type` (type: `string`): Filter to image-only or video-only creatives, or include all. ## `match_type` (type: `string`): How Meta should match the keyword/business name. 'broad' (default) matches ads containing all the words in any order (Meta's search\_type=keyword\_unordered). 'exact' matches ads containing the exact phrase (Meta's search\_type=keyword\_exact\_phrase). Ignored when search\_mode = page\_id. ## `max_ads_per_advertiser` (type: `integer`): Hard cap on ads returned for each query. With pagination off, first SSR page (~30 ads) only. ## `follow_pagination` (type: `boolean`): When false, returns only the first SSR page (~30 ads). When true, walks end\_cursor up to max\_ads\_per\_advertiser. ## Actor input object example ```json { "search_mode": "keyword", "query": "Nike", "region": "US", "active_only": true, "media_type": "all", "match_type": "broad", "max_ads_per_advertiser": 60, "follow_pagination": true } ``` # Actor output Schema ## `ads` (type: `string`): One row per ad surfaced. Same ad\_archive\_id can appear multiple times across overlapping batch queries; consumers dedupe. Schema is declared in dataset\_schema.json. ## `summary` (type: `string`): Per-run summary with queries\_executed, advertisers\_resolved, ads\_returned, block\_rate, validation\_error\_rate, aborted state, warnings, and a per-query advertisers\[] array (page\_id, page\_name, total\_count, ads\_in\_dataset, has\_more, end\_cursor, source\_url, truncated\_reason). # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "query": "Nike", "max_ads_per_advertiser": 60, "follow_pagination": true }; // Run the Actor and wait for it to finish const run = await client.actor("jaybird/meta-ad-library-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "query": "Nike", "max_ads_per_advertiser": 60, "follow_pagination": True, } # Run the Actor and wait for it to finish run = client.actor("jaybird/meta-ad-library-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "query": "Nike", "max_ads_per_advertiser": 60, "follow_pagination": true }' | apify call jaybird/meta-ad-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=jaybird/meta-ad-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta (Facebook & Instagram) Ad Library Scraper", "description": "Scrapes Meta's public Ad Library and returns structured ad data. Four lookup modes (page_id, page_url, keyword, batch), opt-in pagination, schema-validated output.", "version": "0.2", "x-build-id": "6oGVkLApYDexcxSkI" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jaybird~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jaybird-meta-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/jaybird~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-jaybird-meta-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/jaybird~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-jaybird-meta-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "search_mode" ], "properties": { "search_mode": { "title": "Search mode", "enum": [ "page_id", "page_url", "keyword", "batch" ], "type": "string", "description": "How to look up ads. page_id and page_url target a specific advertiser; keyword and batch use Meta's keyword search.", "default": "keyword" }, "page_id": { "title": "Facebook Page ID (numeric)", "type": "string", "description": "Required when search_mode = page_id. Numeric ID, e.g. 142023025844028." }, "page_url": { "title": "Facebook Page URL", "type": "string", "description": "Required when search_mode = page_url. e.g. https://www.facebook.com/PetsOnBroadway" }, "query": { "title": "Keyword / business name", "type": "string", "description": "Required when search_mode = keyword. Free-text search across all advertisers." }, "queries": { "title": "Batch queries", "type": "array", "description": "Required when search_mode = batch. One keyword per line. Each query produces its own search results; overlapping queries are NOT deduplicated within a run.", "items": { "type": "string" } }, "region": { "title": "Region (ISO 3166-1 alpha-2)", "type": "string", "description": "Country to filter Meta's Ad Library results to. Defaults to US.", "default": "US" }, "active_only": { "title": "Active ads only", "type": "boolean", "description": "When true, returns only currently-active ads. When false, includes inactive (stopped) ads.", "default": true }, "media_type": { "title": "Media type filter", "enum": [ "all", "image", "video" ], "type": "string", "description": "Filter to image-only or video-only creatives, or include all.", "default": "all" }, "match_type": { "title": "Keyword match type", "enum": [ "broad", "exact" ], "type": "string", "description": "How Meta should match the keyword/business name. 'broad' (default) matches ads containing all the words in any order (Meta's search_type=keyword_unordered). 'exact' matches ads containing the exact phrase (Meta's search_type=keyword_exact_phrase). Ignored when search_mode = page_id.", "default": "broad" }, "max_ads_per_advertiser": { "title": "Max ads per advertiser", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap on ads returned for each query. With pagination off, first SSR page (~30 ads) only.", "default": 30 }, "follow_pagination": { "title": "Follow pagination cursors", "type": "boolean", "description": "When false, returns only the first SSR page (~30 ads). When true, walks end_cursor up to max_ads_per_advertiser.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```