{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta Ad Library Scraper — Ad Creatives, Spend & Targeting",
    "description": "Extract Facebook & Instagram ad creatives, spend ranges, impressions, targeting data, and landing pages from Meta Ad Library $5.00/1K.",
    "version": "1.0",
    "x-build-id": "OVJsZRURz2TWqgExw"
  },
  "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": "Your Meta Graph API access token with ads_read permission. Unlocks spend ranges, impressions, demographics, image/video URLs, and much faster scraping. Without it the actor uses web scraping mode (slower, fewer fields). Get a free token at: https://developers.facebook.com/tools/explorer/"
          },
          "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. Use POLITICAL_AND_ISSUE_ADS for political content, housing/employment/credit for regulated ad categories.",
            "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
          },
          "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 (e.g. 23851234567890123). Use this to monitor a single ad or verify it still exists. Requires Meta API token."
          },
          "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": "Add multiple Meta API tokens to distribute rate limits across tokens. The actor picks one randomly per run. Only needed for very high-volume use (1000+ ads per minute). Leave empty if using the single token above."
          },
          "proxyUrls": {
            "title": "Custom proxy URLs",
            "type": "array",
            "description": "Use your own residential proxies (Webshare, BrightData, Oxylabs, Smartproxy). Format: http://user:pass@host:port. Only applies in web scrape mode (no Meta token). Leave empty to use Apify's built-in proxies."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}