{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Ads Transcript Scraper — Ad Library Video & Image Ads",
    "description": "Facebook & Instagram Ad Library ads transcribed in bulk: video transcripts with the first-3s hook, plus image-ad text. Search by keyword or advertiser — no ad IDs needed — or paste ad links or chain any scraper. No start fee; expired links, text-free images and music-only ads are never charged.",
    "version": "1.0",
    "x-build-id": "T7HQI7iLwMJAtPUBh"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/steadyfetch~facebook-ads-transcript-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-steadyfetch-facebook-ads-transcript-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-ads-transcript-scraper/runs": {
      "post": {
        "operationId": "runs-sync-steadyfetch-facebook-ads-transcript-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-ads-transcript-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-steadyfetch-facebook-ads-transcript-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": "Start here if you have no ad IDs. Type what you want to hear — a keyword like \"fitness app\", or an advertiser's page name like \"Nike\". Each keyword returns the ads currently running in the country below, already transcribed. Leave everything empty and click Start and the run is a 3-ad sample (currently running US video ads matching \"fitness app\", charged like any run) — the fastest way to see real output. Keywords that match nothing ship as free, 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.",
            "default": "US"
          },
          "mediaType": {
            "title": "Ad format to search for",
            "type": "string",
            "description": "\"video\" (default) returns video ads to transcribe. \"all\" also returns image ads, whose on-image text is read instead. Only used with search keywords.",
            "default": "video"
          },
          "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.",
            "default": "active"
          },
          "searchMaxAds": {
            "title": "Max ads per keyword",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "How many ads each search keyword may return. Keeps a broad keyword from turning into a large bill.",
            "default": 25
          },
          "adLibraryUrls": {
            "title": "Ad Library links",
            "type": "array",
            "description": "Paste links to individual ads, e.g. https://www.facebook.com/ads/library/?id=123456789 (the ad's \"Copy ad link\", or your browser's address bar when an ad is open). The actor finds the ad's video for you. A bare ad ID works too. Links it can't resolve — removed ads, or a temporary block — ship as free, clearly-labelled rows and are never charged.",
            "items": {
              "type": "string"
            }
          },
          "videoUrls": {
            "title": "Ad video URLs",
            "type": "array",
            "description": "Facebook video CDN links (video.*.fbcdn.net) — the video_hd_url / video_sd_url field from any Ad Library scraper result. Note: fbcdn URLs expire within hours-to-days, so transcribe soon after scraping. (Ad Library page links pasted here are resolved automatically.)",
            "items": {
              "type": "string"
            }
          },
          "datasetId": {
            "title": "Dataset ID (chain a scraper run)",
            "type": "string",
            "description": "The default dataset ID of a finished ad-library scraper run. With Apify's 'Connect actor' integration this is filled automatically — the cleanest way to chain."
          },
          "datasetItems": {
            "title": "Dataset items (paste rows)",
            "type": "array",
            "description": "Paste rows from your ad-library scraper run. The actor deep-scans each row for the ad's video or image URL + metadata (CTA, page name, ad archive ID) — works with any scraper's output shape. Leave it empty to search by keyword or use the other inputs instead."
          },
          "includeImageText": {
            "title": "Extract image-ad text",
            "type": "boolean",
            "description": "ON (default): image ads get their on-image text read and delivered as `imageText` — each delivered extraction is charged like a video transcript (same event, same price; never a long-video surcharge). Images with no readable text are always free. OFF: image ads pass through free as `image_skipped` rows with their metadata, as before.",
            "default": true
          },
          "includeOnScreenText": {
            "title": "Read on-screen text on silent ads",
            "type": "boolean",
            "description": "OFF (default): a silent or music-only video ad ships as a free `no_audio` row, as it always has. ON: the actor also reads the text on screen in such an ad and delivers it as `onScreenText` — many silent ads put their whole message on the screen. A delivered on-screen extraction is charged like a video transcript (same event, same price; never a long-video surcharge). A silent ad with no readable on-screen text stays free.",
            "default": false
          },
          "watchlistId": {
            "title": "Watchlist name",
            "type": "string",
            "description": "A short name for the list, e.g. `acme-competitors` (letters, numbers and hyphens). The list lives in a named key-value store in your account called `fb-ads-watch-<name>`, so you can inspect or clear it any time. Leave empty for a one-off run."
          },
          "newAdsOnly": {
            "title": "New ads only",
            "type": "boolean",
            "description": "OFF (default): every ad runs as usual and rows carry `isNew` / `firstSeenAt`. ON (needs a watchlist name): ads already on your watchlist are skipped before download — not fetched, not charged — and the run's status line and OUTPUT say how many. Only an ad the actor actually answered goes on the list (a delivered transcript, image text or on-screen text, or a final free verdict such as no speech); an ad it could not answer — a failed download, a link it could not resolve, an ad your cost cap left out — is not, so the next run tries it again.",
            "default": false
          },
          "maxAds": {
            "title": "Max ads to process",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Safety cap on how many ads to transcribe in one run. Long videos: the first 3 minutes of every video are included in the transcript price; each started minute beyond that is charged as a \"Long-video minute (surcharge)\" at $0.005 — only when the transcript is delivered, never on image ads or on-screen text.",
            "default": 1000
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}