{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ad Library Scraper [From $0.3💰] · Reach · Transcripts",
    "description": "[From $0.3💰] Facebook Ads Library Scraper — search the Meta Ad Library by keyword or page URL and export every ad: creatives, copy, spend & impressions, EU reach & transparency, advertiser pages, run dates. Opt-in video ad transcripts with the spoken first-3s hook. Filter by country, status, media.",
    "version": "0.0",
    "x-build-id": "7NqHBZUNKprdTuGk2"
  },
  "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>.",
            "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": "Two-letter country codes (<code>US</code>, <code>GB</code>, <code>DE</code> …) or <code>ALL</code> for worldwide. Each country is queried separately per search term. Defaults to <code>US</code>.",
            "items": {
              "type": "string"
            }
          },
          "adActiveStatus": {
            "title": "Ad status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Filter by whether ads are currently running.",
            "default": "active"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "video"
            ],
            "type": "string",
            "description": "Filter ads by creative media type.",
            "default": "all"
          },
          "adType": {
            "title": "Ad category",
            "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 that started in this window. 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": "Started on or after (YYYY-MM-DD)",
            "type": "string",
            "description": "Only include ads that started running on or after this date. Format <code>YYYY-MM-DD</code>. Leave empty to skip.",
            "default": ""
          },
          "startDateMax": {
            "title": "Started on or before (YYYY-MM-DD)",
            "type": "string",
            "description": "Only include ads that started running on or before this date. Format <code>YYYY-MM-DD</code>. Leave empty to skip.",
            "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 delay for API call",
            "type": "integer",
            "description": "Minimum delay to wait before calling the new items from API.",
            "default": 5
          },
          "maxDelay": {
            "title": "Max delay for API call",
            "type": "integer",
            "description": "Maximum delay to wait before calling the new items from API",
            "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 actor already routes all traffic through its own built-in residential proxy 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. Letters, numbers, hyphens, underscores."
          },
          "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 actor will output detailed debug logs including proxy info, session details, response headers, and content structure analysis. Useful for troubleshooting.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}