{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ad Library Scraper · Meta Ads · Reach [From $0.3💰]",
    "description": "[From $0.3💰] Facebook & Meta Ads Library Scraper — search the Meta Ad Library by keyword or page URL and export every ad: creatives, copy, spend & impressions, EU reach & transparency, advertisers, run dates. Opt-in video transcripts with the spoken first-3s hook. Filter by country, status, media.",
    "version": "0.0",
    "x-build-id": "Fy8rQ61F54J4cgD7s"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/memo23~facebook-ads-library-scraper-ppe/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-memo23-facebook-ads-library-scraper-ppe",
        "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/memo23~facebook-ads-library-scraper-ppe/runs": {
      "post": {
        "operationId": "runs-sync-memo23-facebook-ads-library-scraper-ppe",
        "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/memo23~facebook-ads-library-scraper-ppe/run-sync": {
      "post": {
        "operationId": "run-sync-memo23-facebook-ads-library-scraper-ppe",
        "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": {
          "startUrls": {
            "title": "Start URLs",
            "maxItems": 5,
            "type": "array",
            "description": "Paste full Meta Ad Library URLs (with any filters), a single-ad link (<code>https://www.facebook.com/ads/library/?id=123…</code>), or Facebook Page URLs. This is the most powerful mode — it supports every Ad Library filter (country, media type, status, keyword/phrase, date range, political/housing/employment categories, publisher platform, language). Example: <code>https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&is_targeted_country=false&media_type=all&q=nike&search_type=keyword_unordered</code> — or a page URL like <code>https://www.facebook.com/Nike</code>. Typed a plain term or brand here instead (<code>Netflix</code>, <code>Netflix.com</code>)? It is searched as a keyword, the same as if you had put it in <b>Search terms</b> below.",
            "items": {
              "type": "string"
            }
          },
          "advertisers": {
            "title": "Advertiser Page IDs",
            "type": "array",
            "description": "Scrape every ad from specific advertisers. Enter one or more Facebook <b>Page IDs</b> (the numeric id, e.g. <code>103582046420186</code>), or paste an Ad Library page URL that contains <code>view_all_page_id=…</code>. Each advertiser's ads are returned in full. Works on its own or alongside the URL and keyword inputs. Country follows the Countries filter below (or worldwide if unset).",
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "Keywords or brand names to look up in the Meta Ad Library — e.g. <code>nike</code>, <code>weight loss</code>, <code>black friday</code>. Each term is searched separately. Leave empty if you're pasting URLs above. The fields below apply to these search terms.",
            "items": {
              "type": "string"
            }
          },
          "searchCountries": {
            "title": "Countries (ISO 2-letter codes)",
            "type": "array",
            "description": "Where the ads were shown, as two-letter codes such as <code>US</code>, <code>GB</code> or <code>DE</code>, or <code>ALL</code> for every country. Every search term runs once for each country you list; an advertiser uses only the first. Empty means <code>US</code> for search terms and every country for advertisers.",
            "items": {
              "type": "string"
            }
          },
          "adActiveStatus": {
            "title": "Running status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Keep ads still live today, ads that have stopped, or both.",
            "default": "active"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "video"
            ],
            "type": "string",
            "description": "Filter ads by creative media type.",
            "default": "all"
          },
          "adType": {
            "title": "Ad type",
            "enum": [
              "all",
              "political_and_issue_ads",
              "housing_ads",
              "employment_ads",
              "credit_ads"
            ],
            "type": "string",
            "description": "Filter by ad category. <b>All ads</b> covers every commercial ad. The special categories (Political & issue, Housing, Employment, Credit) are the regulated transparency categories — these carry impression/reach data.",
            "default": "all"
          },
          "publisherPlatforms": {
            "title": "Publisher platforms",
            "type": "array",
            "description": "Only return ads shown on these platforms. Valid values: <code>facebook</code>, <code>instagram</code>, <code>messenger</code>, <code>audience_network</code>. Leave empty for all platforms.",
            "items": {
              "type": "string"
            }
          },
          "contentLanguages": {
            "title": "Content languages (ISO codes)",
            "type": "array",
            "description": "Only return ads whose creative is in these languages. Use ISO 639-1 two-letter codes (<code>en</code>, <code>es</code>, <code>de</code> …). Leave empty for all languages.",
            "items": {
              "type": "string"
            }
          },
          "searchMode": {
            "title": "Keyword match",
            "enum": [
              "keyword_unordered",
              "keyword_exact_phrase"
            ],
            "type": "string",
            "description": "<b>Broad</b> matches any of the words; <b>Exact phrase</b> matches the words together (auto-wrapped in quotes).",
            "default": "keyword_unordered"
          },
          "sortBy": {
            "title": "Sort ads by",
            "enum": [
              "",
              "total_impressions",
              "most_recent"
            ],
            "type": "string",
            "description": "How to order the ads returned. <b>Default</b> keeps Facebook's own ranking. <b>Most impressions first</b> sorts by total impressions (works best for Facebook Page ad searches / EU-transparency ads; commercial ads without impression data may be unaffected).",
            "default": ""
          },
          "dateRange": {
            "title": "Date range (preset)",
            "enum": [
              "",
              "last24h",
              "last7d",
              "last14d",
              "last30d"
            ],
            "type": "string",
            "description": "Only ads shown during this window, including ones launched earlier that were still running. Applied to keyword search, pasted Ad Library URLs, and page searches — unless <code>startDateMin</code> / <code>startDateMax</code> are set, which win. Leave empty to skip.",
            "default": ""
          },
          "startDateMin": {
            "title": "Shown on or after (YYYY-MM-DD)",
            "type": "string",
            "description": "Keep ads that were shown on or after this date, as <code>YYYY-MM-DD</code>. An ad launched earlier still counts if it ran into this day. Empty means no lower limit.",
            "default": ""
          },
          "startDateMax": {
            "title": "Shown on or before (YYYY-MM-DD)",
            "type": "string",
            "description": "Keep ads that were shown on or before this date, as <code>YYYY-MM-DD</code>. Empty means no upper limit.",
            "default": ""
          },
          "includeAdReach": {
            "title": "Include Ad Reach and EU transparency in output",
            "type": "boolean",
            "description": "Include Ad Reach and EU transparency in output.",
            "default": false
          },
          "includeTotalActiveAds": {
            "title": "Include total active ads count per page in output",
            "type": "boolean",
            "description": "Include total active ads count per page in output.",
            "default": false
          },
          "filterDuplicatePageIds": {
            "title": "Filter duplicate page IDs",
            "type": "boolean",
            "description": "If enabled, only one ad per unique page_id will be kept (first occurrence). This removes duplicate ads from the same page.",
            "default": false
          },
          "categories": {
            "title": "Filter ads by categories",
            "type": "array",
            "description": "You can add one more categories to filter ads by their categories like: brand, etc. Write one category per input/line.",
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "Maximum items per crawl",
            "type": "integer",
            "description": "Maximum number of items that will be scraped per crawl. Example: `50`. Default `10000`. On a free Apify plan a run is capped at 30 ads and to ONE search target — the first start URL, search-term/country pair or advertiser the input builds, whichever comes first — so a free run with 2 terms x 2 countries returns only the first combination. Paying Apify accounts remove both caps.",
            "default": 10000
          },
          "minDelay": {
            "title": "Min pause between result pages (seconds)",
            "type": "integer",
            "description": "Shortest pause, in seconds, before the next page of results is loaded.",
            "default": 5
          },
          "maxDelay": {
            "title": "Max pause between result pages (seconds)",
            "type": "integer",
            "description": "Longest pause, in seconds, before the next page of results is loaded.",
            "default": 10
          },
          "maxConcurrency": {
            "title": "Max Concurrency",
            "type": "integer",
            "description": "Maximum number of pages that can be processed at the same time.",
            "default": 10
          },
          "minConcurrency": {
            "title": "Min Concurrency",
            "type": "integer",
            "description": "Minimum number of pages that will be processed at the same time.",
            "default": 1
          },
          "maxRequestRetries": {
            "title": "Max Request Retries",
            "type": "integer",
            "description": "Number of times the crawler will retry a failed request before giving up.",
            "default": 100
          },
          "proxy": {
            "title": "Proxy configuration (optional override)",
            "type": "object",
            "description": "Leave empty: the default works out of the box at no extra cost to you. Only set this if you want to use your own proxies."
          },
          "watchlistId": {
            "title": "Watchlist ID",
            "type": "string",
            "description": "Named key-value store that remembers which ads (by ad_archive_id) this run already delivered. Use the same id on a schedule (for example <code>nike-daily</code>) and later runs leave them out, so a monitored advertiser or keyword bills only the ads that are new. Type any short name — it is folded into the form the platform stores (<code>meta_us_massage_gun</code> is kept as <code>meta-us-massage-gun</code>)."
          },
          "newAdsOnly": {
            "title": "Only new ads",
            "type": "boolean",
            "description": "When enabled, ads already stored on the Watchlist ID are left out of the dataset and not charged. The search itself still runs in full. Requires <code>watchlistId</code>. Default: false.",
            "default": false
          },
          "transcribeVideos": {
            "title": "Transcribe video ads",
            "type": "boolean",
            "description": "When on, each ad that has a video is transcribed via the Video & Audio Transcriber and the row gains `transcript`, `transcriptLanguage` and `hookSpoken` (the first 3 seconds of speech). Image-only ads are saved as usual with no transcription charge. Off by default — existing scrape-only runs are unchanged. Billed by the transcriber at $0.05 per started minute of audio (up to 3 minutes per video, about $0.05 for a typical ad); failed videos are free. Pair with mediaType = video.",
            "default": false
          },
          "debug": {
            "title": "Enable Debug Logging",
            "type": "boolean",
            "description": "If enabled, the run log carries extra detail on every step. Useful when you report a problem to support.",
            "default": false
          },
          "enrichEmails": {
            "title": "Find the advertiser's contact email",
            "type": "boolean",
            "description": "When on, each advertiser's own website (the one the ad itself links to) is scraped for a contact address, and the row gains `contactEmail`, `contactWebsite` and `emailEnrichment`. One lookup per advertiser, not per ad - a search that returns twenty ads from one company is looked up and billed once. Advertisers with no site of their own, and lookups that find nothing, are free. Off by default.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}