{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta Ad Library Scraper: Facebook & Instagram Ads",
    "description": "Scrape Meta's Ad Library by keyword, advertiser Page or Ad Library URL: ad text, headline, CTA, link, image and video URLs, start date, days running and platforms (Facebook, Instagram, Messenger, Threads), plus EU reach and payer on request. Only-new mode for competitor monitoring. No login.",
    "version": "0.1",
    "x-build-id": "mgIdNWOUM7WsdRxsz"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/humble-echidna~meta-ad-library/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-humble-echidna-meta-ad-library",
        "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/humble-echidna~meta-ad-library/runs": {
      "post": {
        "operationId": "runs-sync-humble-echidna-meta-ad-library",
        "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/humble-echidna~meta-ad-library/run-sync": {
      "post": {
        "operationId": "run-sync-humble-echidna-meta-ad-library",
        "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": {
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "Words to search ads for, one search per line (e.g. running shoes, or a brand name). Each line is searched in the Ad Library with the filters below, like typing it into the Ad Library search box. A line that is an ad's library ID (e.g. 1870984290951787) finds that ad. Leave empty if you only use Pages or Ad Library URLs.",
            "default": [
              "running shoes"
            ],
            "items": {
              "type": "string"
            }
          },
          "pages": {
            "title": "Advertiser Pages",
            "type": "array",
            "description": "Facebook Pages whose ads you want, one per line: the Page address (https://www.facebook.com/nike), its numeric Page ID (15087023444, shown on the Page under About > Page transparency) or an Ad Library address with view_all_page_id. A Page address is matched to its ID through the Page's own ads; if that fails, paste the Page ID. Every ad the Page runs is returned, filtered by the options below.",
            "items": {
              "type": "string"
            }
          },
          "adLibraryUrls": {
            "title": "Ad Library URLs",
            "type": "array",
            "description": "Addresses copied from facebook.com/ads/library after searching there, one per line, e.g. https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=coffee&search_type=keyword_unordered. Filters in the address (country, active status, media type, platforms, dates) win; filters it leaves out come from the options below. A single-ad address (?id=...) returns that ad.",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "Where the ads ran: a two-letter country code (US, GB, DE, FR, BR...) or ALL for every country. Ads that ran in the EU come with EU reach figures when Ad details is on.",
            "default": "ALL"
          },
          "activeStatus": {
            "title": "Active status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "`active` (running now, the default), `inactive` (stopped) or `all`.",
            "default": "active"
          },
          "adType": {
            "title": "Ad category",
            "enum": [
              "all",
              "political_and_issue_ads",
              "housing_ads",
              "employment_ads",
              "financial_products_and_services_ads"
            ],
            "type": "string",
            "description": "`all` ads (the default), or only one of Meta's special categories: `political_and_issue_ads`, `housing_ads`, `employment_ads`, `financial_products_and_services_ads`.",
            "default": "all"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "video",
              "meme",
              "image_and_meme",
              "none"
            ],
            "type": "string",
            "description": "Only ads with this kind of media: `all` (the default), `image`, `video`, `meme`, `image_and_meme`, or `none` (text only).",
            "default": "all"
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Only ads shown on these Meta platforms: facebook, instagram, messenger, audience_network, threads, whatsapp. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "facebook",
                "instagram",
                "messenger",
                "audience_network",
                "threads",
                "whatsapp"
              ],
              "enumTitles": [
                "Facebook",
                "Instagram",
                "Messenger",
                "Audience Network",
                "Threads",
                "WhatsApp"
              ]
            }
          },
          "searchMode": {
            "title": "Search terms match",
            "enum": [
              "any_words",
              "exact_phrase"
            ],
            "type": "string",
            "description": "`any_words` (the default) finds ads with the words in any order; `exact_phrase` only ads with the exact phrase. Applies to Search terms.",
            "default": "any_words"
          },
          "dateFrom": {
            "title": "Shown from",
            "type": "string",
            "description": "Only ads shown on or after this day (YYYY-MM-DD), Meta's own date filter: an ad started earlier that was still shown on this day counts. Leave empty for no start."
          },
          "dateTo": {
            "title": "Shown until",
            "type": "string",
            "description": "Only ads shown on or before this day (YYYY-MM-DD). Leave empty for no end."
          },
          "maxAdsPerQuery": {
            "title": "Max ads per search",
            "minimum": 1,
            "type": "integer",
            "description": "Stop each search term, Page or URL after this many ads, e.g. 50. Meta lists the most recent ads first. Minimum 1.",
            "default": 50
          },
          "maxResults": {
            "title": "Max results per run",
            "minimum": 1,
            "type": "integer",
            "description": "Stop after this many ads in total, across every search, e.g. 500. Minimum 1; leave empty (the default) for no limit. The run also stops cleanly at the maximum cost per run you set in the run options, whichever comes first. Set it to keep a run small and quick."
          },
          "includeDetails": {
            "title": "Ad details (EU reach, payer, advertiser)",
            "type": "boolean",
            "description": "Also read each ad's details panel: EU reach (total and by country, age and gender, for ads shown in the EU), EU targeting (locations, ages, gender), who paid for the ad and who it benefits, and the advertiser's Page category, likes and Instagram account. One extra request per ad, so runs take longer; no extra charge. Off by default.",
            "default": false
          },
          "onlyNew": {
            "title": "Only new ads",
            "type": "boolean",
            "description": "Return only ads this search hasn't returned in an earlier run, for monitoring a competitor's or a keyword's new ads on a schedule. Remembered per search line and filter set in a key-value store in your account (meta-ad-library-seen). A search stops after 3 pages in a row with nothing new, since Meta lists the most recent ads first.",
            "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
                  },
                  "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}