{ "openapi": "3.0.1", "info": { "title": "Meta Ad Library Scraper — Facebook & Instagram Ads + EU Reach", "description": "Every ad a page runs on Facebook, Instagram, Messenger, WhatsApp and Threads as one flat row: headline, body, CTA, landing URL, image and video URLs, run dates, platforms. Optional EU reach and audience per ad, political spend ranges. Honest counts, only-new-ads monitoring, proxies handled.", "version": "0.1", "x-build-id": "E0nl0CKchUIc1zHMy" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hyperbach~meta-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hyperbach-meta-ads-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/hyperbach~meta-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-hyperbach-meta-ads-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/hyperbach~meta-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-hyperbach-meta-ads-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", "properties": { "advertiserIds": { "title": "Page IDs (advertisers)", "type": "array", "description": "Numeric Facebook page IDs, e.g. `20409006880` (Shopify) — the `view_all_page_id` value in an advertiser's Ad Library URL. The whole Ad Library URL is accepted too. Every ad the page runs, across Facebook, Instagram, Messenger, WhatsApp, Audience Network and Threads.", "items": { "type": "string", "pattern": "^\\s*([0-9]{3,20}|\\S*/ads/library\\S*[?&]view_all_page_id=[0-9]{3,20}(&\\S*)?)\\s*$" }, "default": [] }, "advertiserNames": { "title": "Advertiser names (brands)", "type": "array", "description": "Brand or company names, e.g. `Nike`. Each is resolved to the Facebook pages advertising under that name — the pages behind the ads a name search returns, ranked by how well the page name matches — and those pages are then scraped (`resultType: ads`) or listed (`resultType: advertisers`). Use `maxAdvertisersPerName` to control how many pages per name are followed.", "default": [], "items": { "type": "string" } }, "searchTerms": { "title": "Keyword searches", "type": "array", "description": "Keywords or brand names, e.g. `shopify`. A keyword search is Meta's ranked sample across every advertiser — the Ad Library returns at most a few hundred creatives for any keyword, whatever total it displays. To get everything one advertiser runs, use its page ID instead. `keywordMatch` chooses loose or exact-phrase matching.", "default": [], "items": { "type": "string" } }, "creativeIds": { "title": "Ad Library IDs (single ads)", "type": "array", "description": "Library IDs of individual ads, e.g. `1657481092030542` — the `id` in an Ad Library URL (the whole URL is accepted too). One lookup each.", "items": { "type": "string", "pattern": "^\\s*([0-9]{6,20}|\\S*/ads/library\\S*[?&]id=[0-9]{6,20}(&\\S*)?)\\s*$" }, "default": [] }, "resultType": { "title": "Return", "enum": [ "ads", "advertisers", "counts" ], "type": "string", "description": "`ads` returns one record per ad creative. `advertisers` returns one record per page that `advertiserNames` or `searchTerms` resolve to — page id, name, categories, likes, how many matching ads it runs — so you can see which page a brand advertises under before pulling its ads (the same idiom as our Google Ads Transparency Scraper). `counts` returns one record per target with the total the Ad Library shows for it, from a single page load and without scraping any ad.", "default": "ads" }, "maxAdvertisersPerName": { "title": "Max pages per advertiser name", "minimum": 1, "type": "integer", "description": "How many resolved pages to follow for each entry in `advertiserNames`. A common name can match several pages (regional pages, resellers); the best name match ranks first.", "default": 3 }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Paste Ad Library URLs — an advertiser page (`...?view_all_page_id=...`), a keyword search (`...?q=...`) or a single ad (`...?id=...`). A Facebook page URL (`facebook.com/shopify`) works too: the Actor finds the advertiser whose page name is that name, and returns nothing rather than a different page when no name matches. A `country` in the URL is used unless you set `region` explicitly.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "region": { "title": "Country", "pattern": "^\\s*([A-Za-z]{2}|[Aa][Ll][Ll])\\s*$", "type": "string", "description": "Two-letter country code for where the ads were shown, e.g. `US`, `GB` (`UK` also works), `DE`, or `ALL` for every country at once — the same `country=` value the Ad Library puts in its URLs. Leave it empty and the country in a pasted `startUrls` URL is used, or `ALL` when there is none. The EU transparency figures (`includeEuReach`) do not depend on this: they come back for any ad that reached the EU whatever country you ask for." }, "regions": { "title": "Countries (several)", "type": "array", "description": "Several country codes in one run, e.g. `[\"DE\", \"FR\", \"IT\"]` — ads shown in any of them. Wins over `region` when given; `ALL` in the list means every country. Rows carry the list in `region`.", "items": { "type": "string", "pattern": "^\\s*([A-Za-z]{2}|[Aa][Ll][Ll])\\s*$" }, "default": [] }, "targetedCountryOnly": { "title": "Only ads targeting the country", "type": "boolean", "description": "With a country in `region`/`regions`: ask the Ad Library for ads whose advertiser targeted that country, not every ad that happened to be shown there — its own 'targeted' switch, passed through as is. Measured 2026-09-20 on a page and on a keyword search in DE: the first 30 rows were identical with and without it, so expect a small difference at most. No effect with `ALL`.", "default": false }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "`active` returns ads running now, `inactive` ads that have stopped, `all` both. Inactive ads are how you read a competitor's history: what they tried and dropped.", "default": "active" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue", "housing", "employment", "financial_products" ], "type": "string", "description": "`all` for every ad. `political_and_issue` narrows to ads about social issues, elections or politics — the only ads Meta publishes spend, impressions and reach for; those arrive as ranges in `spend_min`/`spend_max`, `impressions_min`/`impressions_max` and `reach_min`/`reach_max`, with the funding entity in `paid_for_by`. `housing`, `employment` and `financial_products` are Meta's special ad categories.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Keep only creatives of this media type, as the Ad Library's own filter defines them. `all` is every type.", "default": "all" }, "platforms": { "title": "Platforms", "type": "array", "description": "Keep only ads that ran on these Meta platforms. Empty means all. Every row also lists where it ran in `platforms`.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger", "whatsapp", "threads" ] }, "default": [] }, "languages": { "title": "Content languages", "type": "array", "description": "Keep only creatives in these languages, as two-letter ISO 639-1 codes, e.g. `[\"es\", \"pt\"]` — the Ad Library's own language filter. Empty means all.", "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "default": [] }, "sortBy": { "title": "Sort order", "enum": [ "auto", "relevance", "most_recent", "most_impressions", "least_impressions" ], "type": "string", "description": "`auto` picks the order that reaches the most: for an advertiser the newest-first order walks every creative in a straight line (measured: relevance starts repeating after ~1,240), for a search term relevance yields more. `most_impressions` / `least_impressions` order by Meta's impressions bucket, which exists on ads about social issues, elections or politics only.", "default": "auto" }, "expandVariants": { "title": "Every ad behind each creative", "type": "boolean", "description": "The Library groups ads that share a creative and text (\"N ads use this creative\") and shows one per group; its result count counts them all. On, each group is opened and every ad in it is a row of its own — the count the Library shows, the way the lane's biggest actors deliver it (Shopify: 1,753 creatives, 5,597 ads). Off, one row per creative with `collation_count` saying how many ads use it: fewer rows, fewer fees, the creative-level view.", "default": true }, "keywordMatch": { "title": "Keyword matching", "enum": [ "unordered", "exact_phrase" ], "type": "string", "description": "How `searchTerms` match ad text: `unordered` finds ads containing the words in any order, `exact_phrase` only the phrase as typed. A pasted search URL keeps its own `search_type`.", "default": "unordered" }, "keywordRelevance": { "title": "Keyword relevance", "enum": [ "any", "visible" ], "type": "string", "description": "A keyword search is the Ad Library's loose match: `shopify` also returns ads that mention the word in passing. Every keyword row carries `matched_fields` — which of its texts (headline, body, cards, link, advertiser name) contain the whole term. `visible` keeps only rows with at least one such field; `any` keeps everything the Library returned.", "default": "any" }, "dedupeBy": { "title": "Dedupe keyword results", "enum": [ "none", "advertiser" ], "type": "string", "description": "`advertiser` keeps one ad per advertiser in a keyword search — a who-is-advertising-on-this read instead of every creative. `none` keeps all.", "default": "none" }, "startDate": { "title": "Shown on or after", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string", "description": "`YYYY-MM-DD`. Keeps ads whose run overlaps this date or later — an ad that started years ago and is still running counts, because it is still running." }, "endDate": { "title": "Shown on or before", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string", "description": "`YYYY-MM-DD`. Keeps ads whose run overlaps this date or earlier." }, "period": { "title": "Launched in the last…", "enum": [ "", "last24h", "last7d", "last14d", "last30d", "last90d" ], "type": "string", "description": "Keep only creatives that started running in the window: the last 24 hours, 7, 14, 30 or 90 days. A preset over `first_shown`; combine with `sortBy: most_recent` for a 'what did they launch this week' read. Empty means no window.", "default": "" }, "longRunningDays": { "title": "Long-running threshold (days)", "minimum": 1, "type": "integer", "description": "An ad shown for at least this many days gets `long_running: true` — the fastest read on which creatives earn their budget. Default 30.", "default": 30 }, "includeEuReach": { "title": "Include EU reach and audience", "type": "boolean", "description": "One extra request per ad that adds what the Ad Library publishes under the EU Digital Services Act: total EU reach, the reach breakdown by country, age and gender, the audience the advertiser chose (age range, gender, included and excluded locations) and the payer and beneficiary. Present on ads that reached the EU, null on the rest; billed only on rows that carry a figure. Also fills the advertiser columns below.", "default": false }, "includeAdvertiserInfo": { "title": "Include advertiser page facts", "type": "boolean", "description": "One extra request per advertiser (not per ad) that fills `advertiser_category`, `advertiser_about`, `advertiser_likes`, `advertiser_ig_username`, `advertiser_ig_followers`, `advertiser_verified` and, for political pages, lifetime and last-week spend. Not billed separately.", "default": false }, "downloadMedia": { "title": "Download the creative files", "enum": [ "none", "images", "all" ], "type": "string", "description": "Copy each creative's files from Meta's CDN into a key-value store you own, so the links do not expire with Meta's ~4-day URLs. Every row then carries `media_files` (store URL, size, type per file) plus `image_file_url` / `video_file_url`. Files are keyed by creative id, so a creative met again on a later run is linked to its existing file and not fetched or charged twice. Billed per file written.", "default": "none" }, "mediaStoreName": { "title": "Media store name", "type": "string", "description": "Named key-value store the files go into. Optional: left empty, the name is derived from the targets (`meta-ads-media-…`), so a scheduled task keeps adding to the same store. Set one to collect several inputs into one place, e.g. `creatives-shopify`." }, "transcribeVideos": { "title": "Transcribe video ads", "type": "boolean", "description": "Turn the speech in every video creative into text: `transcript`, `transcript_language` (ISO code), `hook_3s` (the words spoken in the first three seconds of speech) and `speech_seconds`. A music-only or silent video is checked and comes back with `speech_seconds: 0` — and is not billed. Billed per row that carries a transcript.", "default": false }, "ocrImageAds": { "title": "Read the text in image ads", "type": "boolean", "description": "Read the words baked into the artwork with a vision model — the headline set over the photo, the offer sticker, the price — into `ad_ocr_text`. The image read is the creative's first image, or the poster frame of a video ad. Read once per creative and cached. Billed per row where words were found; model usage is included.", "default": false }, "analyzeAds": { "title": "Analyse each ad with a model", "type": "boolean", "description": "One structured read per creative by an OpenAI model: `analysis_hook` (the scroll-stopper), `analysis_offer`, `analysis_angle` (problem_solution, social_proof, scarcity, discount, feature, lifestyle, curiosity, education, comparison, brand, other), `analysis_audience`, `analysis_cta_intent`, `analysis_tone` and `analysis_sentiment` (-1..1). Reads the copy, the cards, the CTA, and the image text and transcript when those switches are on. A free `sentiment_score` (AFINN word list) is on every row regardless. Billed per row analysed; model usage included.", "default": false }, "enrichLandingPage": { "title": "Resolve and read the landing page", "type": "boolean", "description": "Follow each ad's link to the page it lands on: `landing_final_url` (redirects followed, tracking parameters stripped), `landing_domain`, `landing_status`, `landing_title`, and — from the page's own product markup (Open Graph, JSON-LD) — `landing_is_product`, `landing_product_name`, `landing_price`, `landing_currency`. One fetch per distinct URL per run. Billed per row whose page answered.", "default": false }, "openaiApiKey": { "title": "OpenAI API key", "type": "string", "description": "Optional. The Actor uses its own model access by default and bills a flat fee per transcript, image read or analysis. Supply your own OpenAI key only if you would rather the model usage went to your account." }, "summaryRows": { "title": "Add summary rows", "type": "boolean", "description": "After the ads, add one `advertiser_profile` row per advertiser (ad count, active count, longest-running days, formats, landing domains, distinct copies, the ad ids) and one `landing_page` row per destination URL with the ads pointing at it. Computed from the rows already delivered — no extra requests, not billed.", "default": false }, "runTag": { "title": "Run tag", "type": "string", "description": "Your own label for this run — a client name, a campaign, a week — copied into `run_tag` on every row, so rows from several runs sort in one sheet or table." }, "maxAds": { "title": "Max ads", "minimum": 0, "type": "integer", "description": "Stop after this many ads in total, across every search. 0 means no limit.", "default": 0 }, "maxAdsPerTarget": { "title": "Max ads per target", "minimum": 0, "type": "integer", "description": "Cap each page ID, keyword or URL separately. Without this, one prolific advertiser can use the whole `maxAds` budget before the next target starts. 0 means no per-target cap.", "default": 0 }, "onlyNewAds": { "title": "Only ads not seen before", "type": "boolean", "description": "Skip creatives delivered by previous runs of the same targets (or of the same `stateStoreName`). Skipped ads are never returned and never charged — a weekly monitoring run pays only for what actually changed. Every row also carries `first_seen_at` / `last_seen_at` from the same memory.", "default": false }, "includeEndedAds": { "title": "Report ads that ended", "type": "boolean", "description": "With a monitoring memory (the same store `onlyNewAds` uses): after a complete scan of a target, add one `ended` row for every creative earlier runs saw there that the Library no longer returns — with when it was first and last seen. A capped or cut-off scan reports none, because it cannot vouch for an absence. Not billed.", "default": false }, "stateStoreName": { "title": "Monitoring store name", "type": "string", "description": "Name of the memory that holds the creative IDs already delivered, so `onlyNewAds` can tell new from old across runs. The memory is kept by the Actor on its side, one per Apify account — nothing is stored in your account. Optional: left empty, the name is derived from the targets, so a scheduled task remembers on its own. Set one to share memory between different inputs, e.g. `ads-shopify`, or change it to start over." }, "resumeFromRunId": { "title": "Resume an earlier run", "type": "string", "description": "The id of an earlier run of this Actor that timed out or was aborted, with the same input: this run continues from its checkpoint — finished targets skipped, the target in progress continued from its cursor, no creative delivered twice, `maxAds` counted across both. A run that stops on its own can also simply be resurrected (Apify's Resurrect): it finds its own checkpoint." }, "requestDelaySecs": { "title": "Delay between pages", "minimum": 0, "type": "number", "description": "Seconds to wait between result pages. The source paces itself by latency; a small delay keeps one exit useful for longer.", "default": 0.3 }, "concurrency": { "title": "Targets walked at once", "minimum": 1, "maximum": 5, "type": "integer", "description": "How many advertisers or search terms are paged at the same time, each on its own residential exit (the details and variant calls run on a separate pool of three). 3 is measured safe; 5 for a long list of small targets.", "default": 3 }, "includeRawData": { "title": "Include raw source record", "type": "boolean", "description": "Add Meta's own untouched record to each row as `raw`, for callers who would rather map the fields themselves.", "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }