{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta Ad Library Monitor: New Competitor Ads",
    "description": "Monitor the public Meta Ad Library for the advertisers you choose and get only the Facebook and Instagram ads that are new, changed or ended since your last run, with copy, CTA, landing page, media links and an Ad Library link. Schedule it for competitor ad-launch alerts. No login, no API token.",
    "version": "0.1",
    "x-build-id": "GVcnV7SF43llJTcgV"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/singletonops~meta-ad-library-new-ads-monitor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-singletonops-meta-ad-library-new-ads-monitor",
        "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/singletonops~meta-ad-library-new-ads-monitor/runs": {
      "post": {
        "operationId": "runs-sync-singletonops-meta-ad-library-new-ads-monitor",
        "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/singletonops~meta-ad-library-new-ads-monitor/run-sync": {
      "post": {
        "operationId": "run-sync-singletonops-meta-ad-library-new-ads-monitor",
        "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": [
          "advertisers"
        ],
        "properties": {
          "advertisers": {
            "title": "Advertisers",
            "type": "array",
            "description": "Facebook page IDs (e.g. 15087023444), facebook.com page URLs (e.g. https://www.facebook.com/nike), Ad Library URLs with view_all_page_id or q=, or search keywords. Prefix with \"keyword:\" to force a keyword search. To monitor a brand, use its page ID: a keyword matches any advertiser whose ads mention the word.",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "2-letter ISO country code the ads were delivered in, or ALL.",
            "default": "US"
          },
          "activeStatus": {
            "title": "Active status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Which ads to watch. With \"active\" an ad that disappears from a fully scanned list is reported as ended.",
            "default": "active"
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Only ads shown on these platforms. Empty = all platforms.",
            "items": {
              "type": "string",
              "enum": [
                "facebook",
                "instagram",
                "messenger",
                "audience_network",
                "threads"
              ],
              "enumTitles": [
                "Facebook",
                "Instagram",
                "Messenger",
                "Audience Network",
                "Threads"
              ]
            },
            "default": []
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "video",
              "meme",
              "image_and_meme",
              "none"
            ],
            "type": "string",
            "description": "Filter by creative media type.",
            "default": "all"
          },
          "exactPhrase": {
            "title": "Exact phrase (keyword targets)",
            "type": "boolean",
            "description": "For keyword targets only: search the exact phrase (Meta's <code>keyword_exact_phrase</code>, the query is sent in double quotes like the Ad Library UI does) instead of the default any-words search. Page IDs and page URLs ignore it. Turning it on starts its own baseline for the same <code>stateStoreName</code>.",
            "default": false
          },
          "maxAdsPerAdvertiser": {
            "title": "Max ads per advertiser",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Safety cap on ads checked per advertiser per run (30 ads per request). If the cap is hit, ended-ad detection by disappearance is skipped for that advertiser. The form starts at 30 (one page, fastest trial run); raise it for full ended-ad tracking. API runs that omit it use the default of 500.",
            "default": 500
          },
          "longRunningOnly": {
            "title": "Long-running ads only (6+ months)",
            "type": "boolean",
            "description": "Keep only ads that have been running for at least 180 days (<code>daysRunning</code> &ge; 180), the \"proven winners\" an advertiser keeps paying for. Same as <b>Minimum days running</b> = 180; if both are set, the larger value wins. Active ads count up to today; ended ads up to their end date. Ads without a Meta start date are left out while this is on. Filtered-out ads are not saved or charged; <b>Max ads per advertiser</b> still counts every ad checked.",
            "default": false
          },
          "minDaysRunning": {
            "title": "Minimum days running",
            "minimum": 0,
            "maximum": 3650,
            "type": "integer",
            "description": "Keep only ads whose <code>daysRunning</code> (from the delivery start date to today for active ads, or to the end date for ended ads, counting both days) is at least this many days, e.g. 90 or 180. 0 = off (default). Turning the filter on starts its own monitoring baseline; ads already tracked by that baseline are still followed until they end.",
            "default": 0
          },
          "stateStoreName": {
            "title": "State store name",
            "type": "string",
            "description": "Named key-value store that keeps what was seen between runs. Use one name per monitor / schedule. Changing the country or filters starts a fresh baseline automatically.",
            "default": "meta-ad-library-monitor-state"
          },
          "emitAllOnFirstRun": {
            "title": "Output all ads on the first run",
            "type": "boolean",
            "description": "On the first run for an advertiser, output every current ad as \"new\" (isBaseline=true). Turn off to just record a silent baseline.",
            "default": true
          },
          "emitEnded": {
            "title": "Output ended ads",
            "type": "boolean",
            "description": "Output a record when an ad stops running.",
            "default": true
          },
          "includeCreativeVelocity": {
            "title": "Add creative velocity to the summary",
            "type": "boolean",
            "description": "Optional. Adds a <code>creativeVelocity</code> block per advertiser to the free summary record (and a CREATIVE_VELOCITY key-value record): new ads started in the last 7 days, static / video / carousel mix, unique landing pages (domain + path), distinct headline + copy variants and a 0-100 velocity score where 20+ new ads a week is the top band. Uses only ads this run already checked, so it adds no requests and no charges. Counts are a floor when <b>Max ads per advertiser</b> stops the scan early.",
            "default": false
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "Optional. When there are changes, the run summary and up to 200 changed ads are POSTed here as JSON."
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Meta sends logged-out datacenter traffic to a login wall, so residential proxy is the default and strongly recommended.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "maxRetries": {
            "title": "Max retries per request",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Retries with exponential backoff and a fresh proxy session on rate limits / blocks.",
            "default": 4
          },
          "requestTimeoutSecs": {
            "title": "Request timeout (seconds)",
            "minimum": 10,
            "maximum": 180,
            "type": "integer",
            "description": "Per-request timeout.",
            "default": 45
          },
          "pruneEndedAfterDays": {
            "title": "Forget ended ads after (days)",
            "minimum": 1,
            "maximum": 3650,
            "type": "integer",
            "description": "Ended ads are kept in state for this long (so a reactivation is reported as a change), then dropped.",
            "default": 90
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}