{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta Ad Library Scraper — Ad Creatives, Spend & Targeting",
    "description": "Extract Facebook and Instagram ad creatives, spend ranges, impressions, targeting data and landing pages from Meta Ad Library. Works with Apify MCP and the API.",
    "version": "1.3",
    "x-build-id": "3yGFnFCTMPil1pqg7"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~meta-ad-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-meta-ad-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/khadinakbar~meta-ad-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-meta-ad-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/khadinakbar~meta-ad-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-meta-ad-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": {
          "searchQuery": {
            "title": "Search keyword or phrase",
            "type": "string",
            "description": "Keyword or phrase to search in Meta Ad Library. Finds all ads mentioning this term across Facebook, Instagram, and Messenger. Example: 'nike running shoes', 'weight loss', 'crypto'. For MCP/API: pass a plain string."
          },
          "searchQueries": {
            "title": "Multiple keywords (batch search)",
            "type": "array",
            "description": "Run several keyword searches in one go. Each keyword is scraped separately and results are merged. Example: [\"nike\", \"adidas\", \"puma\"]. Leave empty if using the single keyword above.",
            "items": {
              "type": "string"
            }
          },
          "metaAccessToken": {
            "title": "Meta API Access Token",
            "type": "string",
            "description": "Provide your own Meta Graph API access token with ads_read permission for this run. This confidential value is never written to the dataset, output, or logs. Without it the actor uses public web scraping mode."
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Countries where the ads were shown. Use ISO 3166-1 alpha-2 codes. Examples: US, GB, AU, CA, DE, FR, IN, BR. Default is US. For MCP: pass as array of strings, e.g. [\"US\", \"GB\"].",
            "default": [
              "US"
            ],
            "items": {
              "type": "string"
            }
          },
          "adStatus": {
            "title": "Ad status",
            "enum": [
              "ALL",
              "ACTIVE",
              "INACTIVE"
            ],
            "type": "string",
            "description": "ACTIVE = ads currently running (best for competitor research). INACTIVE = stopped ads. ALL = both active and inactive.",
            "default": "ALL"
          },
          "adType": {
            "title": "Ad type",
            "enum": [
              "ALL",
              "POLITICAL_AND_ISSUE_ADS",
              "HOUSING_ADS",
              "EMPLOYMENT_ADS",
              "CREDIT_ADS"
            ],
            "type": "string",
            "description": "Type of ads to include. ALL covers standard commercial ads and works without a token. HOUSING_ADS, EMPLOYMENT_ADS and CREDIT_ADS are regulated categories that Facebook heavily restricts without a metaAccessToken — expect limited or blocked results in those modes unless you provide one.",
            "default": "ALL"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "ALL",
              "IMAGE",
              "VIDEO",
              "MEME",
              "NONE"
            ],
            "type": "string",
            "description": "Filter by creative format. IMAGE = photo ads only. VIDEO = video ads only. ALL = no filter.",
            "default": "ALL"
          },
          "startDate": {
            "title": "Start date (from)",
            "type": "string",
            "description": "Only include ads that were running on or after this date. Format: YYYY-MM-DD. Example: 2024-01-01. Leave empty for no date filter."
          },
          "endDate": {
            "title": "End date (to)",
            "type": "string",
            "description": "Only include ads that were running on or before this date. Format: YYYY-MM-DD. Example: 2024-12-31. Leave empty for no date filter."
          },
          "maxResults": {
            "title": "Max ads to return",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Maximum number of ad records to fetch. 50 = quick sample. 100 = standard run. 500–1000 = deep competitive analysis. Higher = more cost. Default: 100.",
            "default": 100
          },
          "sortBy": {
            "title": "Sort results by",
            "enum": [
              "impressions_desc",
              "most_recent"
            ],
            "type": "string",
            "description": "How to order returned ads. impressions_desc = highest-reach ads first (best for finding what's working). most_recent = newest ads first.",
            "default": "impressions_desc"
          },
          "enrichAds": {
            "title": "Enrich with auto-analysis",
            "type": "boolean",
            "description": "Adds extra fields to every ad: ad_summary (one-line description), detected_cta (call-to-action type), ad_category, running_days, word_count, hashtag_count, emoji_count. Highly recommended for LLM/MCP pipelines. No extra cost.",
            "default": true
          },
          "providerFallbackEnabled": {
            "title": "Use provider fallback",
            "type": "boolean",
            "description": "When the native Meta Graph API or browser scrape returns no ads because of a block, timeout, rate limit, or expired token, try the configured public Meta Ad Library fallback through managed data providers. No user cookies required.",
            "default": true
          },
          "onlyCount": {
            "title": "Count only (no ad data)",
            "type": "boolean",
            "description": "Returns only the total number of matching ads without downloading records. Use this to check how many ads exist before running a full scrape. Very fast and cheap.",
            "default": false
          },
          "advertiserPageIds": {
            "title": "Advertiser Page IDs",
            "type": "array",
            "description": "Get all ads from specific Facebook Pages by their Page ID. To find a Page ID: go to the page on Facebook → About → Page ID at the bottom. Example: [\"123456789\", \"987654321\"]. Use this instead of searchQuery to get all ads from a known brand.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Ad Library URLs",
            "type": "array",
            "description": "Paste URLs directly from facebook.com/ads/library after setting your filters in the browser. The actor extracts all filter parameters automatically. Also accepts Facebook Page URLs to scrape all ads from that page.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "adId": {
            "title": "Single Ad ID",
            "type": "string",
            "description": "Look up one specific ad by its Meta Ad Library ID (a real working example: 820508563651991). Use this to monitor a single ad or verify it still exists. Works with or without a Meta API token; a nonexistent or taken-down ad ID finishes with an INVALID_INPUT warning instead of data."
          },
          "contentLanguages": {
            "title": "Content languages",
            "type": "array",
            "description": "Only return ads written in these languages. Use ISO 639-1 codes: en (English), es (Spanish), de (German), fr (French), pt (Portuguese). Leave empty for all languages.",
            "items": {
              "type": "string"
            }
          },
          "publisherPlatforms": {
            "title": "Publisher platforms",
            "type": "array",
            "description": "Filter by which Meta platform the ad ran on. Options: facebook, instagram, messenger, audience_network, threads. Default includes Facebook and Instagram.",
            "default": [
              "facebook",
              "instagram"
            ],
            "items": {
              "type": "string"
            }
          },
          "searchType": {
            "title": "Keyword match type",
            "enum": [
              "KEYWORD_UNORDERED",
              "KEYWORD_EXACT_PHRASE"
            ],
            "type": "string",
            "description": "KEYWORD_UNORDERED = all words must appear but in any order (broader). KEYWORD_EXACT_PHRASE = words must appear exactly as typed (narrower).",
            "default": "KEYWORD_UNORDERED"
          },
          "metaAccessTokens": {
            "title": "Token pool (high-volume)",
            "type": "array",
            "description": "Provide your own Meta Graph API tokens as an array for this run. The actor selects one token per run. These confidential values are never written to the dataset, output, or logs. Leave empty to use metaAccessToken."
          },
          "proxyUrls": {
            "title": "Custom proxy URLs",
            "type": "array",
            "description": "Use your own residential proxies from any provider. Format: http://user:pass@host:port. Only applies in web scrape mode (no Meta token). Leave empty to use Apify's built-in proxies."
          },
          "accessToken": {
            "title": "Legacy Meta credential alias: accessToken",
            "type": "string",
            "description": "Provide your own Meta credential for this run using this existing API alias. Prefer metaAccessTokens for an array or metaAccessToken for a single token. This confidential value is never written to the dataset, output, or logs."
          },
          "token": {
            "title": "Legacy Meta credential alias: token",
            "type": "string",
            "description": "Provide your own Meta credential for this run using this existing API alias. Prefer metaAccessTokens for an array or metaAccessToken for a single token. This confidential value is never written to the dataset, output, or logs."
          },
          "apiToken": {
            "title": "Legacy Meta credential alias: apiToken",
            "type": "string",
            "description": "Provide your own Meta credential for this run using this existing API alias. Prefer metaAccessTokens for an array or metaAccessToken for a single token. This confidential value is never written to the dataset, output, or logs."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}