{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Library Scraper",
    "description": "Search the public Facebook / Meta Ad Library by keyword, advertiser Page or Ad Library URL. Ad copy, creative media, CTA, delivery dates, platforms and transparency ranges, with optional advertiser and landing-page enrichment. No login needed. $1 per 1,000 ads.",
    "version": "1.0",
    "x-build-id": "ZGu0sgyexYL1i3Uyt"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/coregent~facebook-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-coregent-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/coregent~facebook-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-coregent-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/coregent~facebook-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-coregent-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",
        "properties": {
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "Keywords or phrases to search the public Ads Library for — the same box you would type into on facebook.com/ads/library. Each term is searched separately in every country you select, so 2 terms × 3 countries is 6 searches sharing one result limit.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "pageUrlsOrIds": {
            "title": "Advertiser Pages",
            "type": "array",
            "description": "Facebook Page URLs, @handles, or numeric Page IDs. Returns every ad that advertiser is running in the countries you select. A handle is resolved to its Ads Library Page ID automatically; if an advertiser you know is advertising comes back empty, paste the numeric `view_all_page_id=` value from their own Ads Library URL instead — that always works.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Ads Library URLs",
            "type": "array",
            "description": "Full public Ads Library search URLs, pasted straight from your browser. The filters already in the URL are used as-is and take priority over the settings below — any disagreement is reported in the log rather than silently resolved.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Two-letter ISO country codes (US, GB, AU, DE …). The Ads Library shows the ads running in a given country, so each country is a separate search. Defaults to US.",
            "default": [
              "US"
            ],
            "items": {
              "type": "string"
            }
          },
          "adStatus": {
            "title": "Ad status",
            "enum": [
              "all",
              "active",
              "inactive"
            ],
            "type": "string",
            "description": "Whether to return ads currently running, ads that have stopped, or both.",
            "default": "all"
          },
          "dateFrom": {
            "title": "Started on or after",
            "type": "string",
            "description": "Only ads whose delivery started on or after this date (YYYY-MM-DD). Also the simplest way to run incrementally — set it to your last run's date.",
            "default": ""
          },
          "dateTo": {
            "title": "Started on or before",
            "type": "string",
            "description": "Only ads whose delivery started on or before this date (YYYY-MM-DD).",
            "default": ""
          },
          "mediaTypes": {
            "title": "Media types",
            "type": "array",
            "description": "Limit to ads using particular creative types. Leave empty for all. Selecting exactly one is applied by Facebook; selecting several is applied after fetching, because the Ads Library accepts only one media type per search.",
            "items": {
              "type": "string",
              "enum": [
                "image",
                "video",
                "meme",
                "image_and_meme",
                "none"
              ],
              "enumTitles": [
                "Image",
                "Video",
                "Meme",
                "Image and meme",
                "No media (text only)"
              ]
            },
            "default": []
          },
          "maxResults": {
            "title": "Maximum ads",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Total ads to return across every search in this run. Reached fairly: searches are interleaved, so one broad keyword cannot consume the whole limit before your other inputs have run.",
            "default": 100
          },
          "onlyTotalCount": {
            "title": "Count only — do not return ads",
            "type": "boolean",
            "description": "Preflight mode: report how many ads each search matches and return no ad rows. FREE — no ad-result events are charged. Facebook publishes this figure as a live estimate and caps it at 50,000, so a result of 50,001 means '50,000 or more' and is flagged as such in the output.",
            "default": false
          },
          "includeAdDetails": {
            "title": "Include full creative details",
            "type": "boolean",
            "description": "Include the full creative in each row: link description, CTA text, every image and video URL, and all carousel cards. FREE — this data arrives in the same response as the base ad, so switching it off makes rows narrower, not cheaper. On by default.",
            "default": true
          },
          "includeAdvertiserDetails": {
            "title": "Enrich advertiser details",
            "type": "boolean",
            "description": "Fetch each advertiser's own Facebook Page for public contact and business data: email, phone, WhatsApp, website, street address and coordinates, price range, services and recommend/review figures. CHARGED once per unique advertiser, never per ad — an advertiser with 200 ads in your results is one charge. A Page that cannot be read, or that publishes none of these, is not charged.",
            "default": false
          },
          "includeLandingPageEnrichment": {
            "title": "Enrich landing pages",
            "type": "boolean",
            "description": "Follow each ad's destination link and extract the page title, description, emails, phones and social links. CHARGED once per unique domain, never per ad — fifty ads pointing at one shop is one charge. A site that is unreachable, blocked, or publishes nothing is not charged.",
            "default": false
          },
          "adType": {
            "title": "Ad category",
            "enum": [
              "all",
              "political_and_issue_ads",
              "housing_ads",
              "employment_ads",
              "credit_ads"
            ],
            "type": "string",
            "description": "Meta's regulated ad categories. Political, housing, employment and credit ads publish extra transparency data (spend and impression ranges, funding entity) that ordinary commercial ads do not.",
            "default": "all"
          },
          "publisherPlatforms": {
            "title": "Publisher platforms",
            "type": "array",
            "description": "Limit to ads shown on particular Meta platforms. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "facebook",
                "instagram",
                "audience_network",
                "messenger",
                "whatsapp",
                "threads"
              ],
              "enumTitles": [
                "Facebook",
                "Instagram",
                "Audience Network",
                "Messenger",
                "WhatsApp",
                "Threads"
              ]
            },
            "default": []
          },
          "exactPhrase": {
            "title": "Match the exact phrase",
            "type": "boolean",
            "description": "Search terms must appear as a whole phrase rather than as loose words. Narrower and usually far more precise for brand or product names.",
            "default": false
          },
          "skipAdIds": {
            "title": "Skip these ad IDs",
            "type": "array",
            "description": "Ad archive IDs you already have. They are skipped before anything is fetched, enriched or charged — the simplest way to run this on a schedule and pay only for what is new.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxResultsPerSource": {
            "title": "Maximum ads per search",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Safety cap on how many ads any single keyword, advertiser or URL may contribute. 0 means no per-search cap — only the overall maximum applies.",
            "default": 0
          },
          "advertiserNameInclude": {
            "title": "Advertiser name must contain",
            "type": "array",
            "description": "Keep only ads whose advertiser name contains one of these (case-insensitive). Applied after fetching — the Ads Library has no such filter.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "advertiserNameExclude": {
            "title": "Advertiser name must not contain",
            "type": "array",
            "description": "Drop ads whose advertiser name contains one of these (case-insensitive). Ads with no advertiser name are kept.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "contentLanguages": {
            "title": "Content languages",
            "type": "array",
            "description": "Two-letter language codes to limit results to. Leave empty for all languages.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify RESIDENTIAL proxy is recommended and is what this Actor is built for. Measured on the platform: Facebook rate-limits the Apify Datacenter pool on the pagination request, so a datacenter run returns only the first ~30 ads per search while reporting success. Datacenter and no-proxy still fetch page one. Custom proxy URLs from your own provider are honoured in full.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}