{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta Ads Library Scraper [💰$0.05/1k]",
    "description": "Scrape Meta's Ad Library across Facebook, Instagram, WhatsApp, Threads, Messenger and Audience Network: ad copy, image and video URLs, landing page, platforms and days running. Switch on EU transparency for per-ad reach with an age, gender and country breakdown.",
    "version": "0.1",
    "x-build-id": "z7yAMRBocG6CR8KeE"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~meta-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-meta-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/blackfalcondata~meta-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-meta-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/blackfalcondata~meta-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-meta-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",
        "properties": {
          "query": {
            "title": "🔍 Search Term(s)",
            "type": "string",
            "description": "Keyword(s) to search the Ad Library for — a brand, product, or phrase that appears in the ad copy or advertiser name. Required if no startUrls provided."
          },
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "Paste raw Ad Library search URLs (https://www.facebook.com/ads/library/?q=...&country=US or ?view_all_page_id=...). Each URL becomes its own search task; results are merged and deduped by ad archive ID across all URLs. Search Term(s) still run alongside them. Filters set below (status, category, media type, platforms, languages, start dates) apply to every URL that does not carry that filter itself; a filter in the URL always wins. Links that are not Ad Library links are skipped with a warning; if none is, the run stops.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "country": {
            "title": "🌍 Country",
            "enum": [
              "ALL",
              "US",
              "GB",
              "CA",
              "AU",
              "DE",
              "FR",
              "ES",
              "IT",
              "NL",
              "SE",
              "DK",
              "PL",
              "BR",
              "MX",
              "IN"
            ],
            "type": "string",
            "description": "Ad Library country the ads were delivered in. ALL searches every country. A Start URL's own country wins; this is used for URLs without one.",
            "default": "US"
          },
          "activeStatus": {
            "title": "🟢 Ad Status",
            "enum": [
              "ALL",
              "ACTIVE",
              "INACTIVE"
            ],
            "type": "string",
            "description": "Only ads currently running, only ads that have stopped, or both. Also applied to Start URLs without active_status; a URL that has active_status keeps its own.",
            "default": "ALL"
          },
          "adType": {
            "title": "🗂️ Ad Category",
            "enum": [
              "ALL",
              "POLITICAL_AND_ISSUE_ADS",
              "HOUSING_ADS",
              "EMPLOYMENT_ADS",
              "CREDIT_ADS"
            ],
            "type": "string",
            "description": "Meta files some ads in regulated categories. \"All ads\" covers ordinary commercial advertising. Pick \"Political & issue ads\" to search the library Meta publishes spend, reach and impression figures for — those columns are filled only there, and come back empty on commercial ads. Also applied to Start URLs without ad_type; a URL that has ad_type keeps its own.",
            "default": "ALL"
          },
          "mediaType": {
            "title": "🖼️ Media Type",
            "enum": [
              "ALL",
              "IMAGE",
              "VIDEO",
              "MEME",
              "NONE"
            ],
            "type": "string",
            "description": "Restrict to image ads, video ads, or memes. Also applied to Start URLs without media_type; a URL that has media_type keeps its own.",
            "default": "ALL"
          },
          "searchType": {
            "title": "🔤 Keyword Matching",
            "enum": [
              "KEYWORD_UNORDERED",
              "KEYWORD_EXACT_PHRASE"
            ],
            "type": "string",
            "description": "Match the search term as separate words, or as an exact phrase. Also applied to Start URLs without search_type; a URL that has search_type keeps its own.",
            "default": "KEYWORD_UNORDERED"
          },
          "publisherPlatforms": {
            "title": "📱 Platforms",
            "type": "array",
            "description": "Only ads shown on these Meta platforms. Leave empty for all of them. Also applied to Start URLs without publisher_platforms; a URL that has publisher_platforms keeps its own.",
            "items": {
              "type": "string",
              "enum": [
                "FACEBOOK",
                "INSTAGRAM",
                "AUDIENCE_NETWORK",
                "MESSENGER",
                "THREADS",
                "WHATSAPP"
              ]
            },
            "default": []
          },
          "contentLanguages": {
            "title": "🗣️ Ad Languages",
            "type": "array",
            "description": "ISO language codes, e.g. en, de, da. Leave empty for all languages. Also applied to Start URLs without content_languages; a URL that has content_languages keeps its own.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "startDateMin": {
            "title": "📅 Started After",
            "type": "string",
            "description": "Only ads that started running on or after this date (YYYY-MM-DD). Also applied to Start URLs without start_date[min]; a URL that has start_date[min] keeps its own."
          },
          "startDateMax": {
            "title": "📅 Started Before",
            "type": "string",
            "description": "Only ads that started running on or before this date (YYYY-MM-DD). Also applied to Start URLs without start_date[max]; a URL that has start_date[max] keeps its own."
          },
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum total ads to return. The Ad Library is cursor-paginated and hands back about 10 ads per request after the first page, so large numbers mean long runs.",
            "default": 100
          },
          "includeDetails": {
            "title": "🇪🇺 Fetch EU reach & audience per ad",
            "type": "boolean",
            "description": "Fetches each ad's EU transparency record: total reach in the EU, the age/country/gender breakdown of who saw it, the targeting parameters the advertiser set, plus the advertiser's Instagram handle, follower count and page description. These numbers are not in the ad list — they come from one extra request per ad, so a run with this on takes noticeably longer and costs more. Reach and audience are published by Meta only for ads that target the EU; for other ads those fields come back empty.",
            "default": false
          },
          "descriptionMaxLength": {
            "title": "✂️ Description Max Length",
            "minimum": 0,
            "type": "integer",
            "description": "Truncate description to N chars. 0 = no truncation.",
            "default": 0
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Core fields only (for AI-agent/MCP workflows).",
            "default": false
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Compare against previous run state.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Optional. Stable identifier for the tracked search universe. Leave empty to auto-generate from search inputs."
          },
          "skipReposts": {
            "title": "🚫 Skip Reposts",
            "type": "boolean",
            "description": "When incremental mode is on, drop ads that re-run a creative you have already seen under a different ad ID. Matched on the creative itself (copy, destination and media), not on the ad ID.",
            "default": false
          },
          "telegramToken": {
            "title": "🔑 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token (from @BotFather). Required for Telegram notifications."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Telegram chat or channel ID (e.g. \"-100123456789\"). Required when telegramToken is set."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL. Server Settings → Integrations → Webhooks → New Webhook."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL. api.slack.com/messaging/webhooks."
          },
          "notificationLimit": {
            "title": "📊 Max Listings Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of listings included in each notification message (1–20).",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "When Incremental Mode is on, only send notifications for NEW and UPDATED listings. Has no effect outside incremental mode.",
            "default": false
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h (service-conversation window — free since Nov 2024)."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 format without + (e.g. \"436641234567\"). Recipient must have messaged your business number within last 24h."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends."
          },
          "webhookHeaders": {
            "title": "📋 Webhook Headers",
            "type": "object",
            "description": "Optional JSON object of custom headers (e.g. {\"Authorization\":\"Bearer ...\"})."
          },
          "appConnector": {
            "title": "Send results to a connected app",
            "type": "string",
            "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results (including any contact details). Best-effort across MCP connectors as Apify expands its catalog."
          },
          "mcpIssueTeam": {
            "title": "Issue tracker team",
            "type": "string",
            "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one."
          },
          "descriptionFormat": {
            "title": "Description format",
            "enum": [
              "all",
              "text",
              "html",
              "markdown"
            ],
            "type": "string",
            "description": "Pick a single description representation. `all` keeps every variant; `text` / `html` / `markdown` drop the others.",
            "default": "all"
          },
          "excludeEmptyFields": {
            "title": "Exclude empty fields from output",
            "type": "boolean",
            "description": "Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}