{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Library Scraper — Meta & Instagram Ads + EU Reach",
    "description": "Scrape the Facebook Ads Library (Meta Ad Library): Facebook, Instagram, Messenger & Threads ads with copy, images, videos, CTAs, landing URLs. Optional EU reach by age, gender & country plus targeting. Search by URL, keyword, Page ID or ad ID. MCP-ready for AI agents.",
    "version": "2.1",
    "x-build-id": "tOvoQ2qhBdlRYOZdY"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/affiliatescope~meta-ads-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-affiliatescope-meta-ads-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/affiliatescope~meta-ads-scraper/runs": {
      "post": {
        "operationId": "runs-sync-affiliatescope-meta-ads-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/affiliatescope~meta-ads-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-affiliatescope-meta-ads-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": {
          "urls": {
            "title": "Ad Library URLs",
            "type": "array",
            "description": "One `facebook.com/ads/library` URL per line. Every filter in the URL is kept (country, status, platforms, languages, dates, sort). Works for searches, Page views (`?view_all_page_id=`) and single ads (`?id=`). Plain Page URLs like `facebook.com/nike` are skipped — use Page IDs.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "searchQueries": {
            "title": "Search queries (keywords)",
            "type": "array",
            "description": "Free-text search terms, one per line. Example: `nike`, `black friday`, `home insurance quote`. Each query runs against every country in the Countries filter below.",
            "items": {
              "type": "string"
            }
          },
          "pageIds": {
            "title": "Facebook Page IDs",
            "type": "array",
            "description": "Numeric Page IDs, one per line. Returns every currently-indexed ad from each Page. Find the ID in any Page's Ad Library URL: `facebook.com/ads/library/?view_all_page_id=<THIS_NUMBER>`.",
            "items": {
              "type": "string"
            }
          },
          "adIds": {
            "title": "Ad IDs",
            "type": "array",
            "description": "Numeric `ad_archive_id` values, one per line (e.g. `1191898553123641`). One ad in, one ad out; filters don't apply. `facebook.com/ads/library/?id=…` links in Ad Library URLs work the same way.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "ISO-3166 alpha-2 country codes, e.g. `US`, `GB`, `DE`. Defaults to `['US']`. Use `['ALL']` to scrape ads globally (no country filter).",
            "default": [
              "US"
            ],
            "items": {
              "type": "string"
            }
          },
          "activeStatus": {
            "title": "Active status",
            "enum": [
              "ALL",
              "ACTIVE",
              "INACTIVE"
            ],
            "type": "string",
            "description": "`Active only` = ads currently running. `Inactive only` = ads that stopped running. `All` = both.",
            "default": "ALL"
          },
          "adType": {
            "title": "Ad category",
            "enum": [
              "ALL",
              "POLITICAL_AND_ISSUE_ADS",
              "HOUSING_ADS",
              "EMPLOYMENT_ADS",
              "CREDIT_ADS"
            ],
            "type": "string",
            "description": "Filter by Meta's ad category. Only `Political & social-issue` ads come with spend, impressions and paid-for-by fields. `Credit` is Meta's `Financial products and services` category.",
            "default": "ALL"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "ALL",
              "IMAGE",
              "MEME",
              "VIDEO",
              "NONE"
            ],
            "type": "string",
            "description": "Filter by ad creative type. `Meme` = image with overlay text. `No media` = text-only ads.",
            "default": "ALL"
          },
          "publisherPlatforms": {
            "title": "Publisher platforms",
            "type": "array",
            "description": "Leave empty for all platforms. Otherwise any subset of `FACEBOOK`, `INSTAGRAM`, `MESSENGER`, `AUDIENCE_NETWORK`, `THREADS` (case-insensitive).",
            "items": {
              "type": "string"
            }
          },
          "contentLanguages": {
            "title": "Content languages",
            "type": "array",
            "description": "ISO-639 language codes, one per line (e.g. `en`, `de`, `es`). Empty = any language.",
            "items": {
              "type": "string"
            }
          },
          "startDate": {
            "title": "From date",
            "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$",
            "type": "string",
            "description": "Earliest ad delivery date, `YYYY-MM-DD`. Leave empty for no lower bound."
          },
          "endDate": {
            "title": "To date",
            "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$",
            "type": "string",
            "description": "Latest ad delivery date, `YYYY-MM-DD`. Leave empty for no upper bound."
          },
          "sortBy": {
            "title": "Sort results",
            "enum": [
              "TOTAL_IMPRESSIONS_DESC",
              "MOST_RECENT"
            ],
            "type": "string",
            "description": "Order of returned ads, same options as the Ad Library's Sort menu. `Impressions` puts the most-seen ads first (Ad Library default). `Most recent` puts the newest ads first.",
            "default": "TOTAL_IMPRESSIONS_DESC"
          },
          "isTargetedCountry": {
            "title": "Only ads targeting the selected country",
            "type": "boolean",
            "description": "If on, filter out ads that merely reached the country without specifically targeting it. Off = include broadly-targeted ads that happened to appear in the country.",
            "default": false
          },
          "scrapeAdDetails": {
            "title": "Add ad details (EU reach, targeting, advertiser)",
            "type": "boolean",
            "description": "Attach each ad's **See ad details** panel as `ad_details`: EU reach by age × gender × country, targeting, payer/beneficiary, advertiser info (about, IG followers, verification). Billed per ad as `ad-details`, only when Meta returns data. EU reach exists only for EU-delivered ads.",
            "default": false
          },
          "deduplicateAds": {
            "title": "Skip duplicate ads",
            "type": "boolean",
            "description": "When the same ad is found by several sources (e.g. two keywords or two countries), keep only the first copy. Skipped duplicates are not pushed and not charged.",
            "default": true
          },
          "maxAdsPerSource": {
            "title": "Max ads per source",
            "minimum": 0,
            "type": "integer",
            "description": "Cap per URL / keyword / Page (and per country). Default `100`. `0` = no limit — a popular keyword can return 10,000+ ads, so keep a cap to protect your budget.",
            "default": 100
          },
          "maxAds": {
            "title": "Max ads total (hard cap)",
            "minimum": 0,
            "type": "integer",
            "description": "Hard cap across ALL sources combined — the run stops as soon as this many ads are in the dataset. `0` = no global cap (only per-source caps apply).",
            "default": 0
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Sources scraped in parallel. Only helps when you have several sources, and is capped at your source count. With 10 keywords, use 5–10. Above 10, raise memory to 1 GB.",
            "default": 3
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Keep the default (Apify RESIDENTIAL). Meta blocks datacenter proxies, so those runs return 0 ads. Your own proxy URLs must be residential and keep the same IP per session (sticky).",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "runTag": {
            "title": "Run tag",
            "type": "string",
            "description": "Label copied to every record's `__metadata.runTag` — handy for grouping snapshots from scheduled runs."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}