{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ad Library Scraper — Facebook Ads by Keyword & Country",
    "description": "Facebook ads by keyword, advertiser page or country, from the Ad Library: advertiser, page ID, flight dates, live status, platforms, creative text, landing page, media URLs and EU spend bands. From $2.00 per 1,000 ads; transcripts are an opt-in add-on. A search that finds nothing is never charged.",
    "version": "1.0",
    "x-build-id": "QRBOjt5cEaAAdlB6Q"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/steadyfetch~facebook-ad-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-steadyfetch-facebook-ad-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/steadyfetch~facebook-ad-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-steadyfetch-facebook-ad-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/steadyfetch~facebook-ad-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-steadyfetch-facebook-ad-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": {
          "searchQueries": {
            "title": "Search keywords or advertisers",
            "type": "array",
            "description": "Keywords or advertiser page names, e.g. [\"fitness app\", \"Nike\"] — each returns the ads currently running in the country below, as structured rows. Keywords that match nothing ship as clearly-labelled rows and are never charged. A single ad's ID or link belongs in \"Ad Library links\" (`adLibraryUrls`), not here; a website address (`nike.com`) is not a page name and finds nothing. What matches: an advertiser's page name, spelled as it appears on their Facebook page — `Nike`, `Acme Fitness` — or words that appear in the ads themselves, like `fitness app`. The country below is part of the match. Leave everything empty and click Start and the run is a 3-ad sample (currently running US ads matching \"fitness app\", charged like any run) — the fastest way to see real output. Change only the settings below and leave this empty and that sample runs under your settings, with one uncharged note row saying which ones it used.",
            "items": {
              "type": "string"
            }
          },
          "adLibraryUrls": {
            "title": "Ad Library links",
            "type": "array",
            "description": "Paste Ad Library links, one per line. A link to one ad — the ad's \"Copy ad link\" or your browser's address bar (https://www.facebook.com/ads/library/?id=123456789) — or a bare ad ID gives one row per ad, charged only when its row lands. An Ad Library SEARCH link (the address bar after you search) runs that same search — its words, its country (ALL included), exact phrase or not, status and format; a setting the link does not carry comes from this run's own. An advertiser's Ad Library PAGE link (the address bar on their page — it has no `?id=` in it) is read as a search of that advertiser's ads, under the country, format and status you set. Each ad a link's search finds is charged exactly as a keyword search would be, and one uncharged note row says how each link was read. Links it can't resolve — removed ads, or a temporary block — ship as clearly-labelled rows and are never charged.",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "Which country's Ad Library to search — or ALL (also \"worldwide\") for every country. The two-letter code (US, GB, DE, SA …), the three-letter code (USA, GBR, IND), the country's English name (India, \"United Kingdom\") and its name in its own language (Deutschland, España, 日本, مصر) all work — where the run has to read a spelling it tells you on an uncharged note row which market it searched. Only used with search keywords, advertiser page links, and Ad Library search links that do not set their own country.",
            "default": "US"
          },
          "mediaType": {
            "title": "Ad format to search for",
            "type": "string",
            "description": "\"all\" (default) returns every ad format. \"video\" returns only ads with a video creative — what you want when you also turn on the transcript. Only used with search keywords and advertiser page links.",
            "default": "all"
          },
          "activeStatus": {
            "title": "Ads to include",
            "type": "string",
            "description": "\"active\" (default) returns ads running right now — what you usually want for competitor research. \"all\" also includes ads that have stopped running. Only used with search keywords and advertiser page links.",
            "default": "active"
          },
          "startedAfter": {
            "title": "Only ads that started on or after",
            "type": "string",
            "description": "A day: YYYY-MM-DD, or 2026/01/31, 31 Jan 2026, a timestamp (its UTC day), or a span back from the run's start: 7 days ago, last week, yesterday, today. Compared with the ad's Ad Library **start date** (the day it first ran), not with impressions or activity dates. Ads that started earlier are dropped after the search and never charged. The Ad Library has no date filter on this query, so this is applied to what the search returns — a narrow window may return fewer ads than \"Max ads per keyword\". Leave empty for no lower bound."
          },
          "startedBefore": {
            "title": "Only ads that started on or before",
            "type": "string",
            "description": "A day, in any form the filter above takes: YYYY-MM-DD, 2026/01/31, a timestamp, or a span such as 7 days ago or yesterday. Ads whose Ad Library start date is later are dropped after the search and never charged. Applied the same way as the filter above. Leave empty for no upper bound."
          },
          "searchMaxAds": {
            "title": "Max ads per keyword",
            "minimum": 1,
            "type": "integer",
            "description": "How many ads each search keyword or advertiser page may return. Keeps a broad keyword from turning into a large bill. Up to 500 per keyword; ask for a bigger number and the run continues at 500, with one uncharged row saying so.",
            "default": 25
          },
          "includeTranscript": {
            "title": "Add the ad's transcript",
            "type": "boolean",
            "description": "OFF (default): you get the ad row only, charged as one \"Ad\". ON: every ad with a video creative is also transcribed and the row carries `transcript`, `hook3s`, `language`, `durationSeconds` and timestamped `segments` — charged as one extra \"Ad transcript\" on top of the ad row, and ONLY when a transcript is actually delivered. A silent or music-only ad, an image ad, an expired video link and a failed transcription all still ship their ad row and are never charged for the transcript. The first 3 minutes of each video are included in the transcript price; each started minute beyond that is charged as a \"Long-video minute (surcharge)\".",
            "default": false
          },
          "maxAds": {
            "title": "Max ads to return",
            "minimum": 1,
            "type": "integer",
            "description": "Hard ceiling — the run never delivers or bills more ad rows than this, across every keyword and link, whatever else is set. Other scrapers call this `resultsLimit` or `maxItems`; those names are read as this field too (`maxItems`, `resultsLimit`, `limit` and `count`, the smallest wins, with one uncharged note row saying what was read). Each delivered row is charged one \"Ad\". Up to 10,000 per run; ask for a bigger number and the run continues at 10,000, with one uncharged row saying so.",
            "default": 100
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}