{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Library Scraper - Creative & Reach ($0.50/1k)",
    "description": "Scrape ads from the Facebook (Meta) Ad Library by keyword or Page - no login, no Meta API key. Full ad creative (text, images, video, CTA, link), advertiser, run dates, ad duration & EU/UK reach. $0.50 per 1,000 ads. 70+ fields per ad. Works with AI Agents, MCP, n8n, Make & Zapier.",
    "version": "0.0",
    "x-build-id": "Ezg93u4vHbwTarPRz"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/harshmaur~facebook-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-harshmaur-facebook-ads-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/harshmaur~facebook-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-harshmaur-facebook-ads-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/harshmaur~facebook-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-harshmaur-facebook-ads-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "urls"
        ],
        "properties": {
          "urls": {
            "title": "🔗 URLs",
            "type": "array",
            "description": "Facebook Ad Library search URLs (from https://www.facebook.com/ads/library) and/or Facebook Page URLs to scrape the ads run by those pages. Both types can be mixed.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "count": {
            "title": "#️⃣ Total number of ads",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum number of ads to scrape across ALL input URLs combined. Defaults to 100 if left blank. Set 0 explicitly for no limit (scrape until each source runs out)."
          },
          "limitPerSource": {
            "title": "#️⃣ Limit per input URL",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum number of ads to scrape per input URL. Leave empty (or 0) to scrape all available ads for each URL."
          },
          "scrapeAdDetails": {
            "title": "Scrape ad details",
            "type": "boolean",
            "description": "Also fetch per-ad detail data (advertiser info + EU/UK transparency: total reach, audience age & gender, target countries). Adds one extra request per ad, so it is slower and costs more.",
            "default": false
          },
          "scrapePageAds.period": {
            "title": "Date range",
            "enum": [
              "",
              "last24h",
              "last7d",
              "last14d",
              "last30d"
            ],
            "type": "string",
            "description": "Only return page ads that started within this window.",
            "default": ""
          },
          "scrapePageAds.activeStatus": {
            "title": "Active status",
            "enum": [
              "all",
              "active",
              "inactive"
            ],
            "type": "string",
            "description": "Filter page ads by whether they are currently active.",
            "default": "all"
          },
          "scrapePageAds.sortBy": {
            "title": "Sort by",
            "enum": [
              "impressions_desc",
              "most_recent"
            ],
            "type": "string",
            "description": "Order page ads by impressions (default) or by most recently created.",
            "default": "impressions_desc"
          },
          "scrapePageAds.countryCode": {
            "title": "Country",
            "type": "string",
            "description": "2-letter ISO country code (e.g. US, GB, IN) to scope page ads to one country, or ALL for every country.",
            "default": "ALL"
          },
          "runTag": {
            "title": "Run tag",
            "type": "string",
            "description": "Optional label copied to the 'runTag' field of every output record — handy for grouping results across runs."
          },
          "mcpConnector": {
            "title": "Send results to an app (MCP connector)",
            "type": "string",
            "description": "Pick an authorized MCP connector (Slack, Notion, Airtable, Google Sheets, …) to receive the scraped ads. This is the recommended, secure path — your credentials stay in Apify and are never exposed to this actor (Apify's proxy injects them). Leave empty to scrape only. Tip: schedule this actor with a 'Last 24 hours' page filter to get pinged whenever an advertiser ships a new ad."
          },
          "mcpMode": {
            "title": "Delivery mode",
            "enum": [
              "perPost",
              "summary"
            ],
            "type": "string",
            "description": "perPost: send one message/record per scraped ad. summary: send a single digest of the whole run.",
            "default": "perPost"
          },
          "mcpTarget": {
            "title": "Target page / database / channel",
            "type": "string",
            "description": "Where to write — the destination ID the tool needs: a Notion database/page ID, a Google Sheet ID, or a Slack channel. Leave blank for connectors that post to a default location. Advanced shapes go in Arguments JSON below."
          },
          "mcpMessage": {
            "title": "Message template",
            "type": "string",
            "description": "Template for each message. Use {{field}} placeholders from ANY ad field — common ones: {{page_name}}, {{ad_text}}, {{headline}}, {{cta_text}}, {{link_url}}, {{ad_library_url}}, {{start_date_iso}}, {{ad_duration_days}}, {{media_type}}, {{is_active}}. Nested/array fields work via dot or [index] paths: {{image_urls.0}}, {{video_urls[0]}}. (Full field list in the README.) Missing fields render empty.",
            "default": "*{{page_name}}*\n{{ad_text}}\n{{ad_library_url}}"
          },
          "mcpTool": {
            "title": "Tool override (advanced)",
            "type": "string",
            "description": "Force a specific tool name on the connector (e.g. send_message, create_page, append_row). Leave empty to auto-detect the connector's write/notify tool."
          },
          "mcpArguments": {
            "title": "Tool arguments override (advanced)",
            "type": "object",
            "description": "Extra/override arguments merged into each tool call as JSON — e.g. {\"channel\": \"#fb-ads\"} for Slack. {{field}} placeholders work inside string values too, so you can nest live data into any shape the tool needs — e.g. Notion: {\"properties\": {\"Advertiser\": {\"title\": [{\"text\": {\"content\": \"{{page_name}}\"}}]}, \"Link\": {\"url\": \"{{ad_library_url}}\"}}}. Use it to satisfy required fields or fully control the payload."
          },
          "mcpMaxItems": {
            "title": "Max ads to send",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Safety cap on how many ads are piped to the connector per run (perPost mode). Protects against flooding the destination.",
            "default": 50
          },
          "mcpServerUrl": {
            "title": "MCP server URL (dev / diagnostic)",
            "type": "string",
            "description": "Advanced/testing only. Connect directly to a raw MCP server URL, bypassing the MCP Connector above. For real use prefer a connector — with a connector your credentials stay in Apify and are never seen by this actor. When set, this overrides the connector."
          },
          "mcpServerToken": {
            "title": "MCP server token (dev / diagnostic)",
            "type": "string",
            "description": "Bearer token for the dev MCP server URL above. Note: a token entered here IS visible to the actor at runtime — for production use an MCP Connector instead, so credentials never leave Apify. Ignored unless the URL is set."
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}