{
  "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": "YFH2Ck2biWX3L7yAg"
  },
  "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 links to individual ads — the ad's \"Copy ad link\" or your browser's address bar (https://www.facebook.com/ads/library/?id=123456789) — one row per ad, charged only when its row lands. A bare ad ID works too. An advertiser's Ad Library PAGE link (the address bar on their page — it has no `?id=` in it) works too: it is read as a search of that advertiser's ads, under the country, format and status you set, and each ad found is charged exactly as a keyword search would be. 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 — the two-letter code (US, GB, DE, SA …). Only used with search keywords and advertiser page links.",
            "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 date, YYYY-MM-DD, compared with the ad's Ad Library **start date** — the day it first ran, as the Library shows it — not with impressions or activity dates. Ads whose start date is earlier are dropped after the search and never charged. The Ad Library itself has no date filter on this query, so the search runs first and this filter is applied to what it returns — a narrow window may therefore 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 date, YYYY-MM-DD. 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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}