{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Competitor Intelligence",
    "description": "Turn public Meta Ad Library data into structured competitor advertising intelligence: ad discovery, creative type, CTA, offer detection, ad age, landing pages, advertiser statistics, deduplication and historical change detection. Deterministic, no AI (V1).",
    "version": "1.0",
    "x-build-id": "IIUYJFDy9VOKyvKID"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/outspoken_strategy~facebook-ads-competitor-intelligence/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-outspoken_strategy-facebook-ads-competitor-intelligence",
        "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/outspoken_strategy~facebook-ads-competitor-intelligence/runs": {
      "post": {
        "operationId": "runs-sync-outspoken_strategy-facebook-ads-competitor-intelligence",
        "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/outspoken_strategy~facebook-ads-competitor-intelligence/run-sync": {
      "post": {
        "operationId": "run-sync-outspoken_strategy-facebook-ads-competitor-intelligence",
        "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": [
          "country"
        ],
        "properties": {
          "searchTerms": {
            "title": "Search terms / competitor names",
            "uniqueItems": true,
            "type": "array",
            "description": "Keywords, brand names or competitor page names to search for in the Meta Ad Library (one search per term). Duplicates are removed automatically. Either this or Page IDs must be provided.",
            "items": {
              "type": "string"
            }
          },
          "pageIds": {
            "title": "Facebook Page IDs (optional)",
            "uniqueItems": true,
            "type": "array",
            "description": "Numeric Facebook Page IDs to collect ads for directly (equivalent to opening a Page's advertiser view in the Ad Library). Useful when a keyword search is too broad. Either this or Search terms must be provided.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "pattern": "^([A-Za-z]{2}|ALL|all)$",
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code used for the Ad Library country filter (e.g. ZA, ZW, GB, US, CA, AU) or ALL for all countries. Invalid codes fail validation – they are never silently interpreted.",
            "default": "ZA"
          },
          "adStatus": {
            "title": "Ad status filter",
            "enum": [
              "ACTIVE",
              "INACTIVE",
              "ALL"
            ],
            "type": "string",
            "description": "Ad Library status filter: ACTIVE (currently running), INACTIVE (no longer running) or ALL.",
            "default": "ACTIVE"
          },
          "searchType": {
            "title": "Keyword match type",
            "enum": [
              "KEYWORD_UNORDERED",
              "KEYWORD_EXACT_PHRASE"
            ],
            "type": "string",
            "description": "How search terms are matched by the Ad Library: any-word match (default) or exact phrase.",
            "default": "KEYWORD_UNORDERED"
          },
          "maxAdsPerSearch": {
            "title": "Maximum ads per search term / page",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Stop collecting once this many unique ads were found for a single search term or page ID. Controls cost and run time.",
            "default": 100
          },
          "startDateMin": {
            "title": "Ad start date – from (optional)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Only include ads that started running on or after this date (YYYY-MM-DD). Applied via the Ad Library date filter where supported."
          },
          "startDateMax": {
            "title": "Ad start date – to (optional)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Only include ads that started running on or before this date (YYYY-MM-DD)."
          },
          "includeInactiveAds": {
            "title": "Keep inactive ads in the output",
            "type": "boolean",
            "description": "When false, ads whose status resolves to INACTIVE are dropped from the output (relevant when Ad status is ALL). Automatically true when Ad status is INACTIVE.",
            "default": false
          },
          "includeLandingPage": {
            "title": "Enrich landing pages",
            "type": "boolean",
            "description": "Visit each ad's public landing page once (no deep crawling) to capture final URL, domain, title, meta description, HTTP status, redirect count and a deterministic page-type classification. Increases run time.",
            "default": true
          },
          "includeMedia": {
            "title": "Include media URLs",
            "type": "boolean",
            "description": "Include publicly accessible image, video and thumbnail URLs for each creative. Media is never downloaded – only source URLs are stored.",
            "default": true
          },
          "includeAdvertiserStatistics": {
            "title": "Compute advertiser statistics",
            "type": "boolean",
            "description": "Aggregate per-advertiser statistics and a competitor comparison from the collected ads. Stored in the run's key-value store (OUTPUT, ADVERTISER_STATISTICS, COMPETITOR_COMPARISON).",
            "default": true
          },
          "enableHistoricalComparison": {
            "title": "Enable historical comparison",
            "type": "boolean",
            "description": "Compare this run against the previous run with the same search configuration (stored in a named key-value store) and label ads NEW / UNCHANGED / MODIFIED; removed ads are listed in the HISTORICAL_COMPARISON summary.",
            "default": false
          },
          "historyStoreName": {
            "title": "History key-value store name",
            "type": "string",
            "description": "Name of the named key-value store used to persist snapshots for historical comparison.",
            "default": "facebook-ads-competitor-intelligence-history"
          },
          "maxConcurrency": {
            "title": "Maximum concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Maximum number of browser pages (search terms) processed in parallel. Also caps parallel landing-page requests.",
            "default": 3
          },
          "maxScrollRoundsWithoutNewAds": {
            "title": "Scroll rounds without new ads before stopping",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Safety stop for infinite scrolling: stop a search when this many consecutive scroll rounds yield no new ads.",
            "default": 4
          },
          "navigationTimeoutSecs": {
            "title": "Navigation timeout (seconds)",
            "minimum": 15,
            "maximum": 300,
            "type": "integer",
            "description": "Timeout for loading an Ad Library results page.",
            "default": 60
          },
          "landingPageTimeoutSecs": {
            "title": "Landing page timeout (seconds)",
            "minimum": 5,
            "maximum": 120,
            "type": "integer",
            "description": "Timeout for a single landing-page request.",
            "default": 20
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Apify Proxy RESIDENTIAL group is strongly recommended: Meta serves the first page of results to datacenter IPs but rejects the pagination requests needed to load more than ~30 ads per search. When RESIDENTIAL is selected the proxy country is matched to the search country automatically.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}