{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta (Facebook & Instagram) Ads Library Scraper",
    "description": "💰From $0.14/1K ads | Scrape all Facebook & Instagram ads of any page from the Meta Ad Library. Extract ad creatives, texts, titles, CTAs, image & HD video URLs, spend, reach and dates. Fast parallel scraping, multiple pages per run, date filters, no login or API key. Daily checks to ensure quality!",
    "version": "0.2",
    "x-build-id": "oh4F2YLuUXRT8L8QV"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/jmlp~meta-ad-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-jmlp-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/jmlp~meta-ad-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-jmlp-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/jmlp~meta-ad-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-jmlp-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",
        "properties": {
          "adLibraryUrls": {
            "title": "Ad Library or Facebook page URLs",
            "type": "array",
            "description": "One or more URLs copied from the browser - each is scraped in the same run (in parallel when Max concurrency > 1). Four kinds work: an Ad Library page URL (view_all_page_id=...), an Ad Library keyword search URL (q=...&search_type=keyword_unordered), a single ad's link (?id=...), which fetches just that ad, and a brand's own Facebook page link (facebook.com/zara, /people/Name/id, /p/Name-id, profile.php?id=..., fb.me/zara), which scrapes that page's ads with the settings below - the page is opened to read the page ID the Ad Library uses, so it is found even when its username isn't its advertiser name. Each Ad Library page or keyword URL is scraped as it reads: its target and every filter it carries - dates, country, active status, sort order, media type, platform, language - and the individual fields below fill in whatever a URL does not carry. Max ads applies globally across all of them.",
            "items": {
              "type": "string"
            }
          },
          "adLibraryUrl": {
            "title": "Ad Library or Facebook page URL (single)",
            "type": "string",
            "description": "Paste a single URL - an Ad Library page URL (view_all_page_id=...), a keyword search URL (q=...), a single ad's link (?id=...) or a brand's own Facebook page link (facebook.com/zara). An Ad Library URL is scraped as it reads: its target and every filter it carries - dates, country, active status, sort order, media type, platform, language - take precedence over the individual fields below; an ad link fetches just that ad, whatever those are set to."
          },
          "pageIDs": {
            "title": "Page IDs or names",
            "type": "array",
            "description": "Several pages to scrape in one run, all using the dates/country/active status set below. Each can be a numeric page id (view_all_page_id in the Ad Library URL), the advertiser's name as the Ad Library shows it (e.g. ZARA), its @username or its facebook.com link, which is opened for the page ID the Ad Library uses. Names are looked up in the Ad Library's own advertiser search: a verified page wins, and if several unverified pages share the name, all of them are scraped, most-liked first. A name that matches no page exactly is searched as a keyword across every advertiser instead (up to 1,000 ads when Max ads is not set) - turn off 'Search by keyword when a page isn't found' to skip such names and namesakes instead. To search keywords on purpose, use the Keywords field.",
            "items": {
              "type": "string"
            }
          },
          "pageID": {
            "title": "Page ID or name",
            "type": "string",
            "description": "The Facebook page to scrape: its numeric page id (the view_all_page_id value from the Ad Library URL), or the advertiser's name as the Ad Library shows it (e.g. ZARA), its @username or its facebook.com link - a name is looked up in the Ad Library's advertiser search, and searched as a keyword if no page has that exact name. Not needed when an Ad Library URL is pasted above, or when you are searching by keyword - clear it in that case, or the page is scraped as well."
          },
          "keyword": {
            "title": "Keyword",
            "type": "string",
            "description": "Search every advertiser's ads for this text instead of scraping one page - the same as typing it into the Ad Library search box. Keyword searches can match tens of thousands of ads, so set Max ads and narrow the country and dates. Runs in addition to any page id set above, so clear Page ID if you only want the keyword."
          },
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "Several keywords to search in one run, each using the search type, dates, country and active status set here. Max ads applies globally across all of them.",
            "items": {
              "type": "string"
            }
          },
          "searchType": {
            "title": "Keyword match type",
            "type": "string",
            "description": "How the keyword(s) are matched. 'Any order' is the Ad Library's own default and matches the words anywhere in the ad; 'exact phrase' matches the words together, in order. Only applies to keyword searches, not page ids (a pasted URL's own search_type wins). Other spellings are read too (exact, any order); one the scraper cannot place means any order, with a warning in the log.",
            "default": "keyword_unordered"
          },
          "minDate": {
            "title": "Start date from",
            "type": "string",
            "description": "YYYY-MM-DD. Returns ads that were DELIVERING during the window (measured) - a long-running ad started earlier still matches. Leave empty for the whole archive - be aware that can be tens of thousands of ads. Facebook silently ignores the filter when minDate equals maxDate, so the actor widens such a query by one day. An ad that is still active but was last delivered before this date is left out, as the Ad Library itself does - turn on 'Keep active ads that last ran before the start date' to get those too."
          },
          "maxDate": {
            "title": "Start date to",
            "type": "string",
            "description": "YYYY-MM-DD, inclusive. Same delivery-window semantics as the from-date."
          },
          "activeStatus": {
            "title": "Active status",
            "type": "string",
            "description": "Which ads to include. 'Active only' matches what the Ad Library UI shows and keeps first runs quick; 'all' covers the page's entire archive, which can be 10-100x larger. Other spellings are read too (Active, running, stopped); one the scraper cannot place means all ads, with a warning in the log.",
            "default": "all"
          },
          "keepActiveBeforeMinDate": {
            "title": "Keep active ads that last ran before the start date",
            "type": "boolean",
            "description": "Off by default: with a start date you get what the Ad Library itself lists for those dates. That leaves out an ad that is still active but was last shown before the start date - for an active ad, the end date is the last day it ran, not a real end. On: an ad that is still active always counts as inside the dates. Each page, keyword or link with a start date is then also asked for its active ads without the date, so it takes one more request per target and a little more proxy traffic. Example from November 2026: one page from 2026-10-15 on gave 44 ads without it and 49 with it. It only applies to dates that reach today - with an end date in the past nothing changes - and not to 'Inactive only'. The run's SUMMARY record counts the ads it added as activeAdsBeforeMinDate.",
            "default": false
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "Pick a country, or type one - a code or a name such as Italy. ALL covers every country the ad ran in. A country the scraper cannot place is searched as ALL, with a warning in the log, so the run never fails over it.",
            "default": "ALL"
          },
          "sortBy": {
            "title": "Sort by",
            "type": "string",
            "description": "The order ads are scraped in, as the Ad Library's own 'Sort by'. 'Impressions: high to low' is its default and the fastest: a big search is walked in several parts at once. 'Most recent' walks each search newest first, as the Ad Library lists it, so Max ads keeps the newest ads - the latest 300 of a keyword, say. Each search is then one walk, a few ads a second, so a big one with no Max ads takes longer. A pasted Ad Library URL keeps its own order: Sort by orders the page and keyword fields, and URLs that carry no order. Other spellings are read too (newest, latest); one the scraper cannot place means impressions, with a warning in the log.",
            "default": "impressions"
          },
          "euTransparency": {
            "title": "EU transparency (EU reach, audience, payer)",
            "type": "boolean",
            "description": "Adds each EU ad's EU transparency, as the Ad Library shows it under 'See ad details': its total reach in the EU (eu_total_reach), that reach by country, age and gender, and the locations, ages and gender it was shown to (eu_transparency), and who paid for it and who it was for (payer_beneficiary_data). Facebook has these for every ad shown in the EU (is_aaa_eligible); other ads get null. It takes one more request per EU ad, so a run takes longer and uses more proxy traffic, which is part of its platform usage. An ad whose details do not come is still saved, with null in them.",
            "default": false
          },
          "keywordFallback": {
            "title": "Search by keyword when a page isn't found",
            "type": "boolean",
            "description": "On (default): a page name or link the scraper can't match to a page is searched as a keyword across every advertiser (up to 1,000 ads), a name with commas is also tried as a list of names, every page sharing a name is scraped, and a page with no matching ads brings its regional pages. Off: only pages the scraper can pin down are scraped - a page link (read from the page itself), a page ID, a verified page or the only page of that name. Anything else is skipped with a warning and brings nothing.",
            "default": true
          },
          "aaaInfoCompat": {
            "title": "Compatible output (aaa_info)",
            "type": "boolean",
            "description": "Adds the fields other Ad Library scrapers return, for pipelines built on them: aaa_info (eu_total_reach, age_country_gender_reach_breakdown and the rest of the EU transparency, with payer_beneficiary_data), start_date_formatted and end_date_formatted (YYYY-MM-DD HH:MM:SS, UTC), and url (the input entry as sent). It turns EU transparency on, which aaa_info is read from.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Use RESIDENTIAL groups. Datacenter IPs get challenged or blocked, so a run on anything else moves to residential proxy as soon as Facebook rate-limits it. Your own proxies work too: give their URLs with {session} where your provider takes a session id, such as http://user-session-{session}:pass@gate.example.com:7000, and each of the scraper's sessions gets an IP of its own; {session:8} makes the id 8 characters long. Plain URLs are used in turn, one per session.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "type": "integer",
            "description": "Parallel scraping sessions. Multiple pages/keywords run in parallel, and a large target is split into parts scraped simultaneously - into its active and inactive ads, or by date range - each on its own residential proxy session, roughly linear speedup: Facebook takes about a second per page of 10 ads, so 20 to 100 sessions are what makes a scrape of tens of thousands of ads fast: 100,000 ads took about 10 minutes at 50 and 8 at 100. A session brings in about 5 ads a second at best, so 75,000 ads on 3 sessions take over 80 minutes, past a one-hour timeout: a run whose ads cannot come in before its timeout says so as soon as Facebook's count shows it, with how many sessions would do it, and carries on, saving its progress for a run with Continue from last run. The run's default memory grows with it (64 MB per session, 512 MB at least, 4 GB at most); a run given less memory than its sessions need runs as many as fit, with a warning. Set to 1 only if you need results in strict impression-ranking order. Values outside 1 to 100 are brought into that range, with a warning.",
            "default": 4
          },
          "maxAds": {
            "title": "Max ads",
            "type": "integer",
            "description": "Stop after this many unique ads, counted globally across all pages and keywords. The crawl terminates as soon as the cap is hit, so this caps both runtime and cost. Prefilled with 100 so your first run finishes in seconds - raise it once you like the output, or clear it to scrape everything with no limit. 0 or empty means no limit."
          },
          "maxAdsPerTarget": {
            "title": "Max ads per target",
            "minimum": 1,
            "type": "integer",
            "description": "Stop each target after this many ads - each page, keyword or link of your input on its own - so one big advertiser can't use up Max ads for the others. A name that leads to several pages shares its limit among them. Empty: no limit per target. Max ads still caps the whole run."
          },
          "trustKnownEmptyDays": {
            "title": "Trust pages known to be empty for (days)",
            "minimum": 0,
            "type": "integer",
            "description": "0 (default, recommended): a page that shows no ads is checked a second time on a fresh connection before it's believed, every run, because a blocked connection also looks empty. A number of days: a page both checks found empty within that many days is believed from one check, which roughly halves the cost of pages without ads (a 20-page run with 17 empty pages went from ~$0.032 to ~$0.018 of usage). After that many days it gets both checks again. The price: if such a page starts advertising and its one check meets a blocked connection, that run misses its ads (about 1 check in 400 is).",
            "default": 0
          },
          "leanFirstPage": {
            "title": "Lean first page (less proxy traffic)",
            "type": "boolean",
            "description": "Off by default. On: once the run has loaded one Ad Library page, every further page, keyword or link gets its first ads the way the Ad Library itself does when you type a new search - with its own query, without loading the whole page again - and a run within an hour of your last one may load no page at all. The ads are the same; what changes is proxy traffic and time: measured on Apify in November 2026, 20 page links used 45% less traffic (about 85% less together with 'Trust pages known to be empty'), and a 90-ad search about 30% less in 6-7 s instead of 10. A first answer that comes back empty is still checked again on a full page load, and the run goes back to full page loads by itself if Facebook refuses or rate-limits the query. Off by default while it is new.",
            "default": false
          },
          "maxPages": {
            "title": "Max pages per shard",
            "type": "integer",
            "description": "Safety cap while testing, applied to each shard separately. Empty = all. 0 or empty means no limit."
          },
          "delayMs": {
            "title": "Delay between pages (ms)",
            "type": "integer",
            "description": "Milliseconds to sleep between page requests. None by default: the network already adds ~700-1500 ms per page. Measured on Apify: without the old 300 ms pause, runs of 3,000 ads were 7-30% faster, with no captcha and no more rate limits. Raise it if captchas appear. Takes precedence over the legacy 'delay' (seconds) field. A negative value means 0.",
            "default": 0
          },
          "pageSize": {
            "title": "Page size",
            "type": "integer",
            "description": "Facebook answers at most 10 ads per page whatever this asks for, and the Ad Library page itself asks for 10 (both measured), so a larger value is sent as 10. Values outside 1 to 100 are brought into that range.",
            "default": 10
          },
          "raw": {
            "title": "Raw output",
            "type": "boolean",
            "description": "Push the unprojected GraphQL ad nodes instead of the fixed output schema. Field names are the same; raw skips the null-filling and key ordering.",
            "default": false
          },
          "proxyRotations": {
            "title": "Proxy rotation attempts",
            "type": "integer",
            "description": "How many fresh proxy sessions a target gets when Facebook blocks or refuses it. A proxy exit that does not answer at all is replaced on its own, without using up these attempts. Values outside 1 to 6 are brought into that range.",
            "default": 3
          },
          "resume": {
            "title": "Checkpoint progress",
            "type": "boolean",
            "description": "Save progress every ~30s so a run that gets migrated or restarted by the platform picks up where it stopped, without duplicating anything. No effect on fresh runs.",
            "default": true
          },
          "continueFromLastRun": {
            "title": "Continue from last run",
            "type": "boolean",
            "description": "If your previous run with the same input was interrupted (aborted, failed, or captcha-cut), scrape only what it missed. Note the earlier ads stay in THAT run's dataset - this run's dataset will contain only the remainder. Leave off to always get a complete dataset in one place.",
            "default": false
          },
          "shardSplitThreshold": {
            "title": "Shard split threshold",
            "type": "integer",
            "description": "A target or part reporting more ads than this is split into parts scraped in parallel instead of walked serially: into its active and inactive ads, then halved by date when its ads ran at different times; ads still running, which every date range up to today holds, are cut by date and walked newest first in a run with Max ads. Never split without a proxy, where every part would ask from the same IP. ~1500 ads is about 150 pages, roughly 6 minutes of serial work per shard. A value below 100 means 100.",
            "default": 1500
          },
          "docId": {
            "title": "Pagination doc_id override",
            "type": "string",
            "description": "Leave empty. A stale cached id is detected and refreshed automatically."
          },
          "proxySessionId": {
            "title": "Proxy session id",
            "type": "string",
            "description": "Pin a specific exit IP, for reproducing a run while debugging. Ignored when maxConcurrency > 1 (every shard needs its own session). Nothing is persisted between runs by default."
          },
          "impersonate": {
            "title": "TLS fingerprint",
            "type": "string",
            "description": "curl_cffi target. Empty string disables impersonation.",
            "default": "chrome146"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}