{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Scraper",
    "description": "Facebook Ads Scraper is a powerful Apify Actor that tracks competitor advertisements across Facebook and Instagram using the Meta Ads Library. This Actor extracts ad creatives, copy, CTAs, offers, and longevity signals, giving you comprehensive insights into what your competitors are advertising.",
    "version": "0.0",
    "x-build-id": "QxUrqAuKwnTSdICJn"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/happitap~facebook-ads-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-happitap-facebook-ads-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/happitap~facebook-ads-scraper/runs": {
      "post": {
        "operationId": "runs-sync-happitap-facebook-ads-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/happitap~facebook-ads-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-happitap-facebook-ads-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",
        "required": [
          "platforms",
          "mode",
          "queries"
        ],
        "properties": {
          "platforms": {
            "title": "Platforms",
            "minItems": 1,
            "uniqueItems": true,
            "type": "array",
            "description": "Platform to monitor. Default is Meta (Facebook/Instagram).",
            "items": {
              "type": "string",
              "enum": [
                "meta"
              ],
              "enumTitles": [
                "Meta (Facebook/Instagram)"
              ]
            },
            "default": [
              "meta"
            ]
          },
          "mode": {
            "title": "Search Mode",
            "enum": [
              "advertiser",
              "keyword",
              "domain"
            ],
            "type": "string",
            "description": "Choose how to search for ads:\n\n- **Brand/Advertiser Monitor**: Search by brand names, advertiser IDs, or page names. Best for tracking specific competitors.\n- **Keyword Monitor**: Search by keywords that appear in ad copy, landing pages, or advertiser names. Best for category research.\n- **Domain/Landing Page Monitor**: Search by domain names (e.g., brand.com). Best for agencies tracking client competitors.",
            "default": "advertiser"
          },
          "queries": {
            "title": "Search Queries",
            "minItems": 1,
            "type": "array",
            "description": "Enter your search queries. The meaning depends on the selected mode:\n\n- **Advertiser mode**: Brand names, advertiser names, or page names (e.g., \"Nike\", \"Adidas\")\n- **Keyword mode**: Keywords to search for in ad copy (e.g., \"skincare\", \"anti-aging\")\n- **Domain mode**: Domain names without protocol (e.g., \"example.com\", \"brand.com\")\n\nYou can enter multiple queries.",
            "items": {
              "type": "string",
              "enumSuggestedValues": [
                "Nike",
                "Adidas",
                "skincare",
                "anti-aging"
              ],
              "enumTitles": [
                "Nike",
                "Adidas",
                "Skincare",
                "Anti-aging"
              ]
            }
          },
          "maxResultsPerQuery": {
            "title": "Max Results Per Query",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum number of ads to fetch per query. Higher values may take longer to process.\n\n- **Recommended**: 100-200 for most use cases. Increase to 500-1000 for comprehensive monitoring.",
            "default": 200
          },
          "geo": {
            "title": "Geographic Targets",
            "minItems": 1,
            "type": "array",
            "description": "Country codes (ISO 3166-1 alpha-2) where ads are targeted. Examples: US, GB, IN, CA, AU.\n\nEnter multiple country codes to search across regions.",
            "items": {
              "type": "string",
              "enumSuggestedValues": [
                "US",
                "GB",
                "CA",
                "AU",
                "DE",
                "FR",
                "IN",
                "JP"
              ],
              "enumTitles": [
                "United States",
                "United Kingdom",
                "Canada",
                "Australia",
                "Germany",
                "France",
                "India",
                "Japan"
              ]
            },
            "default": [
              "US"
            ]
          },
          "dateRangeDays": {
            "title": "Date Range (Days)",
            "minimum": 1,
            "maximum": 365,
            "type": "integer",
            "description": "How far back to search for ads in days. The actor will look for ads that were active within this time period.\n\n- **Recommended**: 30 days for recent monitoring, 60-90 days for broader research.",
            "default": 30
          },
          "adStatus": {
            "title": "Ad Status Filter",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Filter ads by their current status:\n\n- **Active Only**: Only ads currently running\n- **Inactive Only**: Only ads that have stopped running\n- **All**: Both active and inactive ads",
            "default": "all"
          },
          "languages": {
            "title": "Languages (Optional)",
            "type": "array",
            "description": "Language codes (ISO 639-1) to filter ads. Examples: en, es, fr, de. Leave empty to search all languages.\n\nThis is optional and may not be supported by all platforms.",
            "items": {
              "type": "string",
              "enumSuggestedValues": [
                "en",
                "es",
                "fr",
                "de",
                "it",
                "pt",
                "ja",
                "zh"
              ],
              "enumTitles": [
                "English",
                "Spanish",
                "French",
                "German",
                "Italian",
                "Portuguese",
                "Japanese",
                "Chinese"
              ]
            },
            "default": []
          },
          "useApifyProxy": {
            "title": "Use Apify Proxy",
            "type": "boolean",
            "description": "Enable proxy rotation to avoid IP blocks. **Highly recommended** for production use.\n\nWhen enabled, the actor will use Apify's proxy service to rotate IP addresses. This helps prevent blocks from ad transparency libraries.",
            "default": true
          },
          "proxyGroups": {
            "title": "Proxy Groups",
            "type": "array",
            "description": "Proxy groups to use. Available options:\n\n- **RESIDENTIAL**: Residential IP addresses (recommended, slower but more reliable)\n- **DATACENTER**: Datacenter IP addresses (faster but may be blocked more often)\n- **SHADER**: Shader proxy group\n\n- **Recommended**: Use RESIDENTIAL for best results, especially for Meta.",
            "items": {
              "type": "string",
              "enum": [
                "RESIDENTIAL",
                "DATACENTER",
                "SHADER"
              ],
              "enumTitles": [
                "Residential (Recommended)",
                "Datacenter",
                "Shader"
              ]
            },
            "default": [
              "RESIDENTIAL"
            ]
          },
          "proxyCountry": {
            "title": "Proxy Country",
            "enum": [
              "US",
              "GB",
              "DE",
              "FR",
              "CA",
              "AU"
            ],
            "type": "string",
            "description": "Country code for proxy IP addresses. Using proxies from the same country as your target geo can improve success rates.\n\n- **US**: United States (default, best for Meta)\n- **GB**: United Kingdom\n- **DE**: Germany",
            "default": "US"
          },
          "maxConcurrency": {
            "title": "Max Concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Maximum number of concurrent requests. Lower values are safer but slower.\n\n- **Recommended**: 3 for most cases. Reduce to 1-2 if you encounter blocks. Increase to 5-10 only if you have reliable proxies.",
            "default": 3
          },
          "slowMode": {
            "title": "Slow Mode",
            "type": "boolean",
            "description": "Add random delays (1-3 seconds) between requests to avoid blocks. **Highly recommended** for production use.\n\nWhen enabled, the actor will wait between requests, making it slower but significantly reducing the chance of being blocked.",
            "default": true
          },
          "maxRetries": {
            "title": "Max Retries",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Maximum number of retry attempts for failed requests. The actor will automatically retry on network errors, timeouts, and temporary blocks.",
            "default": 3
          },
          "extractOffers": {
            "title": "Extract Offers",
            "type": "boolean",
            "description": "Enable automatic offer extraction and normalization. The actor will:\n\n- Detect offer types (discount_percent, flat_off, bogo, free_shipping, bundle, free_trial, etc.)\n- Extract structured offer details (percent off, amounts, trial days)\n- Normalize CTAs (shop_now, learn_more, sign_up, etc.)\n- Detect marketing angles (social proof, scarcity, urgency, etc.)\n\nEach extraction includes a confidence score (0-1).",
            "default": true
          },
          "downloadCreatives": {
            "title": "Download Creatives",
            "type": "boolean",
            "description": "Download creative assets (images/videos) to Apify Key-Value Store. **Note**: This increases storage usage and processing time.\n\nWhen enabled, all creative assets will be downloaded and stored in the Key-Value store for later access.",
            "default": false
          },
          "computeLongevity": {
            "title": "Compute Longevity Score",
            "type": "boolean",
            "description": "Calculate ad longevity scores based on how long ads have been running. Long-running ads often indicate successful creatives.\n\nScoring:\n- 0-7 days: Score 20\n- 8-21 days: Score 50\n- 22-60 days: Score 80\n- 60+ days: Score 100",
            "default": true
          },
          "onlyNewSinceLastRun": {
            "title": "Only New Ads",
            "type": "boolean",
            "description": "Only return ads that were seen for the first time in this run. Useful for monitoring workflows where you only want to be notified of new ads.\n\n- **Note**: This requires state from previous runs. On the first run, all ads will be marked as new.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}