{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ad Library Scraper — Meta Ads, Winners & Monitor",
    "description": "Scrape the Meta (Facebook & Instagram) Ad Library by keyword, advertiser name, page or URL: copy, creatives, landing pages, days running, winning score, EU/UK reach & targeting included. $0.60/1,000 ads.",
    "version": "0.1",
    "x-build-id": "cCIX12dPBqWw5Al5y"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/tactful_anvil~facebook-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-tactful_anvil-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/tactful_anvil~facebook-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-tactful_anvil-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/tactful_anvil~facebook-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-tactful_anvil-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 (keywords or brands)",
            "type": "array",
            "description": "Keywords searched across all ad copy, e.g. \"running shoes\", \"crm software\", \"weight loss\". One Ad Library search per term. Ad Library URLs pasted here work too.",
            "default": [
              "nike"
            ],
            "items": {
              "type": "string"
            }
          },
          "advertisers": {
            "title": "Advertisers (name, @handle or page URL)",
            "type": "array",
            "description": "Every ad of these advertisers. Type a brand name (\"gymshark\"), an @handle, or paste facebook.com/<page> or instagram.com/<handle> — the Actor finds the page ID for you (exact match first, then verified / most-liked).",
            "items": {
              "type": "string"
            }
          },
          "pageIds": {
            "title": "Advertiser page IDs",
            "type": "array",
            "description": "Numeric Facebook page IDs to pull EVERY ad of one advertiser (find it in any Ad Library link as view_all_page_id=…). Profile URLs with ?id= also work.",
            "items": {
              "type": "string"
            }
          },
          "adLibraryUrls": {
            "title": "Ad Library URLs",
            "type": "array",
            "description": "Paste search URLs copied from facebook.com/ads/library — all filters in the URL (country, media type, platforms, dates, page) are applied as-is.",
            "items": {
              "type": "string"
            }
          },
          "adIds": {
            "title": "Single ads (Ad Library IDs)",
            "type": "array",
            "description": "Look up specific ads by their Ad Library ID (the number in facebook.com/ads/library/?id=…) or paste those links.",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "ISO-2 country where the ads were delivered (US, GB, DE, ID, BR…) or ALL for every country.",
            "default": "ALL"
          },
          "activeStatus": {
            "title": "Ad status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "active = running now (default), inactive = stopped, all = both.",
            "default": "active"
          },
          "adType": {
            "title": "Ad category",
            "enum": [
              "all",
              "political_and_issue_ads",
              "housing_ads",
              "employment_ads",
              "financial_products_and_services_ads"
            ],
            "type": "string",
            "description": "all = every ad. The special categories carry extra transparency data (spend/impressions ranges for political ads).",
            "default": "all"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "video",
              "meme",
              "image_and_meme",
              "none"
            ],
            "type": "string",
            "description": "Filter by creative type.",
            "default": "all"
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Only ads shown on these platforms. Any of: facebook, instagram, messenger, audience_network, threads, whatsapp. Empty = all.",
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "title": "Ad languages",
            "type": "array",
            "description": "ISO-639-1 codes of the ad copy language, e.g. en, es, de. Empty = all.",
            "items": {
              "type": "string"
            }
          },
          "exactPhrase": {
            "title": "Exact phrase",
            "type": "boolean",
            "description": "Search terms must appear as an exact phrase (Meta's \"keyword_exact_phrase\"). Off = any order.",
            "default": false
          },
          "sortBy": {
            "title": "Sort order",
            "enum": [
              "impressions",
              "newest"
            ],
            "type": "string",
            "description": "impressions = Meta's default, highest-impression ads first (best for finding winners). newest = most recently launched first (best for monitoring).",
            "default": "impressions"
          },
          "activeFrom": {
            "title": "Shown on or after",
            "type": "string",
            "description": "YYYY-MM-DD. Meta's date filter (\"impressions by date\"): only ads that were SHOWN on/after this day — they may have started earlier."
          },
          "activeTo": {
            "title": "Shown on or before",
            "type": "string",
            "description": "YYYY-MM-DD. Meta's date filter: only ads that were shown on/before this day."
          },
          "startedAfter": {
            "title": "Launched on or after",
            "type": "string",
            "description": "YYYY-MM-DD. Only ads whose first day (startDate) is on/after this day — i.e. NEW campaigns. Applied by this Actor after fetching; ads filtered out are not charged."
          },
          "maxAdsPerQuery": {
            "title": "Max ads per query",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Stop each search/page/URL after this many unique ads. You pay only for ads delivered.",
            "default": 100
          },
          "minDaysActive": {
            "title": "Min days running (winning ads)",
            "minimum": 0,
            "maximum": 3650,
            "type": "integer",
            "description": "Only deliver ads that have been running at least this many days — long-running ads are the ones making money. Filtered ads are not charged. 0 = off.",
            "default": 0
          },
          "newWithinDays": {
            "title": "\"isNew\" window (days)",
            "minimum": 1,
            "maximum": 365,
            "type": "integer",
            "description": "An ad is flagged isNew=true when it started within this many days.",
            "default": 7
          },
          "onlyNewAds": {
            "title": "Monitor mode: only ads not seen before",
            "type": "boolean",
            "description": "Remembers every ad ID per query across runs (named key-value store). Schedule daily/weekly and receive — and pay for — only ads that are new since the last run. Best with Sort order = newest: each query stops as soon as it reaches last run's ads.",
            "default": false
          },
          "includeAdDetails": {
            "title": "Include ad details (EU/UK reach, targeting, payer)",
            "type": "boolean",
            "description": "Opens each ad's \"See ad details\": total reach and reach by country / age / gender (ads shown in the EU or UK), targeting age, gender and locations, payer & beneficiary, advertiser Instagram handle, followers and verification. Included in the price — turn off only for faster runs.",
            "default": true
          },
          "useResidentialForPaging": {
            "title": "Use residential proxy for paging (recommended)",
            "type": "boolean",
            "description": "Meta blocks paging (ads 31+) from datacenter IPs. With this on, the Actor pages through Apify's residential proxy automatically: about $0.035 of proxy traffic per 1,000 ads, billed by Apify on your plan. Page 1 and ad details always use the free direct route. Off = max ~30 ads per query.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional. Leave empty for the automatic setup above. Select RESIDENTIAL (or your own proxy URLs) to route everything through it."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}