{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Library Scraper & Competitor Tracker",
    "description": "Extract public Facebook and Instagram ads by Page ID, keyword, or Meta Ads Library URL. Get copy, creatives, CTAs, landing page URLs, dates, platforms, and advertiser data. Track new, reused, changed, possibly inactive, confirmed inactive, and reactivated ads.",
    "version": "1.4",
    "x-build-id": "tLGChgSG0cZ98M4Pf"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/miladamirzadeh~facebook-ads-library-tracker/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-miladamirzadeh-facebook-ads-library-tracker",
        "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/miladamirzadeh~facebook-ads-library-tracker/runs": {
      "post": {
        "operationId": "runs-sync-miladamirzadeh-facebook-ads-library-tracker",
        "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/miladamirzadeh~facebook-ads-library-tracker/run-sync": {
      "post": {
        "operationId": "run-sync-miladamirzadeh-facebook-ads-library-tracker",
        "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": {
          "pageIds": {
            "title": "Advertiser Page IDs",
            "type": "array",
            "description": "The advertiser's numeric Facebook Page ID. Use this when you want ads from one exact brand or reliable scheduled monitoring. You can find it in a Meta Ads Library URL after view_all_page_id=. Example: 101694774572.",
            "items": {
              "type": "string",
              "pattern": "^[0-9]{3,32}$"
            },
            "default": []
          },
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "A brand, product, offer, or market phrase to search across advertisers, such as running shoes. Best for discovery and market research. For monitoring one known advertiser, use its Page ID instead.",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "default": []
          },
          "startUrls": {
            "title": "Meta Ads Library URLs",
            "type": "array",
            "description": "Paste a full facebook.com/ads/library URL exactly as it appears in your browser. Filters already present in the URL are preserved. A URL containing view_all_page_id identifies one exact advertiser; a general search URL is for discovery only.",
            "default": [],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "countries": {
            "title": "Countries where ads are shown",
            "type": "array",
            "description": "Choose the audience country where the ads should be visible—not the advertiser's home country. Enter two-letter codes such as US, GB, or DE, or ALL for Meta's all-countries view. Every advertiser/search is checked separately in each country.",
            "items": {
              "type": "string",
              "minLength": 2,
              "maxLength": 3
            },
            "default": [
              "ALL"
            ]
          },
          "maxResultsPerTarget": {
            "title": "Maximum ads per advertiser/search",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum ads returned for each advertiser or search term in each country. The prefilled value keeps the first test small. Remove the limit for complete advertiser monitoring; a limited run will not claim that missing ads became inactive."
          },
          "activeStatus": {
            "title": "Ad status",
            "enum": [
              "all",
              "active",
              "inactive"
            ],
            "type": "string",
            "description": "Filter by the status reported by Meta: all ads, ads currently running, or ads Meta marks inactive. Choose All ads when building a complete advertiser history.",
            "default": "all"
          },
          "startDateMin": {
            "title": "Started on or after",
            "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
            "type": "string",
            "description": "Optional earliest ad start date. Leave empty to include older ads."
          },
          "startDateMax": {
            "title": "Started on or before",
            "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
            "type": "string",
            "description": "Optional latest ad start date. Leave empty for no upper date limit."
          },
          "adType": {
            "title": "Ad category (advanced)",
            "type": "string",
            "description": "Meta Ads Library ad_type value. Keep all for normal commercial-ad research. Change this only when you know the exact value used by a Meta Ads Library URL.",
            "default": "all"
          },
          "mediaType": {
            "title": "Media type",
            "type": "string",
            "description": "Optional Meta Ads Library media_type value. Leave empty to include images, videos, carousels, and other available formats."
          },
          "contentLanguages": {
            "title": "Content languages",
            "type": "array",
            "description": "Optional two-letter ad-content language codes, for example en or de. This filters the language of the ad itself, not the country where it is shown. Leave empty for all languages.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "publisherPlatforms": {
            "title": "Publisher platforms",
            "type": "array",
            "description": "Optional placements such as facebook or instagram. Leave empty to include every platform reported by Meta for the ad.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "tracking": {
            "title": "Keep history and detect changes",
            "type": "boolean",
            "description": "Compare this run with earlier runs that use the same History group name. Enable it to detect new ads, reused creatives, copy/media/landing-page changes, inactivity, and reactivation.",
            "default": false
          },
          "trackingNamespace": {
            "title": "History group name",
            "pattern": "^[A-Za-z0-9_.-]+$",
            "maxLength": 96,
            "type": "string",
            "description": "A stable label that connects related scheduled runs, such as nike-us or client-a-weekly. Keep it unchanged for the same monitoring job. Use a different name for an unrelated brand, country set, or filter setup.",
            "default": "default"
          },
          "outputMode": {
            "title": "Output",
            "enum": [
              "raw",
              "changes",
              "rawAndChanges"
            ],
            "type": "string",
            "description": "Raw ads: full ad records for a normal scrape. Changes only: just new/changed/inactive/reactivated events. Raw ads and changes: full ads in the Default Dataset plus events in a separate Changes Dataset.",
            "default": "raw"
          },
          "includeRawPayload": {
            "title": "Include parsed Meta source record",
            "type": "boolean",
            "description": "Add Meta's complete parsed source object under raw in every ad record. Leave this off for smaller, cleaner Datasets. Enable it only when you need source-level fields for diagnostics, custom parsing, or future migrations.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Connection settings",
            "type": "object",
            "description": "The preselected Apify Residential proxy is recommended for reliable Meta Ads Library access. Most users should leave this unchanged. Public media files are fetched directly so their bytes do not create unnecessary residential-proxy charges.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "concurrency": {
            "title": "Advertisers/searches at the same time",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "How many advertiser/search/country combinations run at once. The default is a safe balance. Higher values may finish sooner but open more proxy sessions.",
            "default": 4
          },
          "mediaConcurrency": {
            "title": "Media files checked at the same time",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "How many image or video files can be verified at once when history is enabled. The default balances speed, memory, and network use.",
            "default": 2
          },
          "requestTimeoutSecs": {
            "title": "Request timeout (seconds)",
            "minimum": 5,
            "maximum": 120,
            "type": "integer",
            "description": "How long one Meta or media request may wait before it is treated as timed out. Increase only for unusually slow network conditions.",
            "default": 30
          },
          "maxRequestAttempts": {
            "title": "Maximum request attempts",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Maximum bounded attempts for temporary connection failures, selected server errors, and rate limits. Missing optional ad fields do not trigger a full retry.",
            "default": 3
          },
          "checkpointEveryPages": {
            "title": "Checkpoint interval (pages)",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Save restart progress after this many completed Meta result pages. Lower values preserve finer progress after an interrupted run but create more storage operations.",
            "default": 5
          },
          "maxMediaBytes": {
            "title": "Largest media file to verify (bytes)",
            "minimum": 1000000,
            "maximum": 500000000,
            "type": "integer",
            "description": "Maximum size downloaded to verify one image or video when history is enabled. The default 100000000 equals 100 MB. Larger assets still appear in raw results, but the Actor avoids definitive new/reused creative claims when it cannot verify the full file.",
            "default": 100000000
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}