{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook & Meta Ad Library Scraper",
    "description": "Scrape ads from the Facebook/Meta Ad Library by keyword, country, ad type, media type, or by Ad Library URL - Plus EU reach  and demographics that other scrapers miss.",
    "version": "0.1",
    "x-build-id": "2mHkOfT8TzJ35UphK"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/refined_numbers~meta-ad-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-refined_numbers-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/refined_numbers~meta-ad-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-refined_numbers-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/refined_numbers~meta-ad-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-refined_numbers-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": {
          "searchTerm": {
            "title": "Search term",
            "type": "string",
            "description": "A single keyword to search the Ad Library for (Meta only allows one keyword per query). Leave empty if you use a Start URL, Page ID, or Ad ID instead."
          },
          "country": {
            "title": "Country",
            "enum": [
              "ALL",
              "US",
              "GB",
              "CA",
              "AU",
              "DE",
              "FR",
              "ES",
              "IT",
              "NL",
              "SE",
              "NO",
              "DK",
              "FI",
              "IE",
              "PT",
              "PL",
              "BR",
              "MX",
              "AR",
              "IN",
              "JP",
              "KR",
              "SG",
              "AE",
              "SA",
              "IL",
              "ZA",
              "NZ",
              "BE",
              "AT",
              "CH",
              "TR",
              "ID",
              "PH",
              "TH",
              "VN",
              "MY"
            ],
            "type": "string",
            "description": "Which country's ads to search. Meta allows one country per query, or 'ALL' for global.",
            "default": "US"
          },
          "startUrl": {
            "title": "Start URL",
            "type": "string",
            "description": "A Facebook Ad Library URL to scrape directly (e.g. a search you built in the browser). Use this for full control over filters. Overrides the search term."
          },
          "pageId": {
            "title": "Facebook Page ID",
            "type": "string",
            "description": "Scrape every ad from a specific advertiser by their numeric Facebook Page ID. Overrides the search term."
          },
          "adId": {
            "title": "Ad Library ID",
            "type": "string",
            "description": "Scrape a single ad by its Ad Library ID (the number shown as 'Library ID' on an ad). Takes priority over all other targets."
          },
          "adType": {
            "title": "Ad category",
            "enum": [
              "all",
              "political_and_issue_ads",
              "housing_ads",
              "employment_ads",
              "credit_ads",
              "financial_products_and_services_ads"
            ],
            "type": "string",
            "description": "Which Ad Library category to search. 'All ads' covers everything; the others are the special transparency categories.",
            "default": "all"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "meme",
              "video",
              "none"
            ],
            "type": "string",
            "description": "Filter ads by their creative media type.",
            "default": "all"
          },
          "activeStatus": {
            "title": "Active status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Whether to include currently running ads, stopped ads, or both.",
            "default": "active"
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "most_relevant",
              "most_recent"
            ],
            "type": "string",
            "description": "Ordering of results in the Ad Library.",
            "default": "most_relevant"
          },
          "maxResults": {
            "title": "Max results",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum number of ads to collect in this run. In 'Scrape ad details' mode this is automatically capped at 400 (the run clicks into each ad, so larger runs would exceed the time limit).",
            "default": 10
          },
          "scrapeAdDetails": {
            "title": "Scrape ad details (EU reach + demographics)",
            "type": "boolean",
            "description": "Click into each ad to extract reach + age/gender/country demographics. Only works for an EU/EEA country, the UK, Brazil, or adType=political_and_issue_ads — Meta does not publish this data for ordinary ads elsewhere, so runs with any other country are rejected. Much slower (one click per ad), capped at 400 ads/run. Leave off for fast scraping of brand, dates, body text, media, and platforms.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}