{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Library Scraper: every ad version, no login",
    "version": "0.1",
    "x-build-id": "h4rQmDockOfjV0NXX"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/alexmorain~facebook-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-alexmorain-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/alexmorain~facebook-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-alexmorain-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/alexmorain~facebook-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-alexmorain-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": {
          "advertisers": {
            "title": "Advertisers",
            "type": "array",
            "description": "Brands whose ads you want, one per line: a name (<code>Decathlon</code>), a Facebook page URL (<code>https://www.facebook.com/Decathlon.France/</code>) or a page ID (<code>122695097770591</code>). A name is looked up the way the Ad Library search box does it, for the country you pick: the log lists the page it chose and the other matches with their IDs. Only that page's ads come out, not every ad that mentions the brand.",
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "Keyword searches, as in the Ad Library search box: every ad whose text matches, from any advertiser. Use it for a market or a product (<code>running shoes</code>), not to follow one brand: a brand name as a keyword also returns resellers and fan pages (20% of the results for <code>decathlon</code> in France, measured).",
            "items": {
              "type": "string"
            }
          },
          "exactPhrase": {
            "title": "Exact phrase",
            "type": "boolean",
            "description": "Search terms match the exact phrase instead of all the words in any order.",
            "default": false
          },
          "adLibraryUrls": {
            "title": "Ad Library URLs",
            "type": "array",
            "description": "Pages copied from facebook.com/ads/library: a search, an advertiser's ads (<code>?view_all_page_id=...</code>) or a single ad (<code>?id=...</code>). The filters in the URL (country, status, media type, platforms, languages, dates) are kept for that URL. One URL per line.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Only ads shown in these countries: two-letter codes like <code>US</code>, <code>GB</code>, <code>FR</code>, or names in English. Leave empty for all countries. Several countries are searched together and each ad comes out once.",
            "items": {
              "type": "string"
            }
          },
          "activeStatus": {
            "title": "Ad status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Active ads are the ones running now. Inactive ads have stopped. The Ad Library keeps inactive ads for 1 year (7 years for political ads).",
            "default": "active"
          },
          "adType": {
            "title": "Ad category",
            "enum": [
              "all",
              "political_and_issue_ads"
            ],
            "type": "string",
            "description": "<b>All ads</b>, or only ads about social issues, elections or politics, which come with spend and impression ranges.",
            "default": "all"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "video",
              "meme",
              "image_and_meme",
              "none"
            ],
            "type": "string",
            "description": "Only ads with this kind of creative.",
            "default": "all"
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Only ads shown on these Meta platforms. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "facebook",
                "instagram",
                "messenger",
                "audience_network",
                "threads",
                "whatsapp"
              ],
              "enumTitles": [
                "Facebook",
                "Instagram",
                "Messenger",
                "Audience Network",
                "Threads",
                "WhatsApp"
              ]
            }
          },
          "languages": {
            "title": "Ad languages",
            "type": "array",
            "description": "Only ads in these languages: two-letter codes like <code>en</code>, <code>fr</code>, <code>de</code>. Leave empty for all.",
            "items": {
              "type": "string"
            }
          },
          "shownFrom": {
            "title": "Shown from",
            "type": "string",
            "description": "Only ads <b>shown</b> on or after this date. Careful: Meta keeps an ad that started earlier and was still running on this date. It is not a launch date filter: read <code>startDate</code> in the results for that."
          },
          "shownUntil": {
            "title": "Shown until",
            "type": "string",
            "description": "Only ads shown on or before this date."
          },
          "includeAllVersions": {
            "title": "Every version of each ad",
            "type": "boolean",
            "description": "The Ad Library groups ads with the same creative and lists one per group (\"This ad has multiple versions\"). On, the Actor opens each group and returns the hidden versions too, each with its own ID, dates and text, marked <code>fromVersionGroup: true</code>. One extra request per group, and each version is priced as an ad. Off, you get exactly what the Ad Library list shows.",
            "default": true
          },
          "pagesPerAdvertiser": {
            "title": "Pages per advertiser name",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many Facebook pages to take for each advertiser <b>name</b>. Big brands run ads from several pages (one per country, per product line). 1 takes the page the Ad Library search box puts first for your country.",
            "default": 1
          },
          "maxAdsPerSearch": {
            "title": "Max ads per search",
            "minimum": 0,
            "type": "integer",
            "description": "Stop each advertiser page, search term or URL after this many ads, versions included. Set <code>0</code> for no cap.",
            "default": 200
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "all",
              "new-only"
            ],
            "type": "string",
            "description": "<b>All ads</b> returns every ad the search finds, on every run.<br><br><b>New ads only</b> keeps a persistent registry of the ads previous runs returned and charged, and returns only ads never returned before: schedule it daily to be told when a competitor launches something new, including a new version added to an existing group. Every run reads the whole search, since the Ad Library does not sort by launch date; you pay only for the new ads.",
            "default": "all"
          },
          "registryKey": {
            "title": "Registry key (New ads only)",
            "type": "string",
            "description": "By default the registry is tied to the exact targets, countries and filters, so changing any of them starts a fresh one. Set your own key to keep one registry while you edit the list."
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "If set, the Actor POSTs a small JSON summary to this URL at the end of the run, <b>only when at least one ad was returned</b>: <code>actor</code>, <code>runId</code>, <code>mode</code>, <code>items</code>, <code>searches</code>. With New ads only and a daily schedule, that is a push notification when a competitor launches ads.<br><br>Use the final URL: a redirect is not followed, except a 307 or 308, which gets the same POST once. An unreachable webhook is logged as a warning and never fails the run. Stored encrypted, since a webhook URL often carries its own access token."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Leave as is. Meta refuses datacenter IPs and a good share of residential ones, so the Actor tries fresh residential IPs until one is accepted, then keeps it. The per-ad price is the same whatever you choose.<br><br>With the plain Apify proxy (<code>{\"useApifyProxy\": true}</code>, typical in API calls) it starts on datacenter IPs and <b>switches to residential by itself</b> when Meta keeps refusing. If you pick your own proxy URLs, the Actor keeps exactly what you chose.",
            "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
                  },
                  "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}