{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Transcript Scraper — Ad Library Video & Image Ads", "description": "Facebook, Instagram and Meta 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 a scraper. No start fee; expired links, text-free images and music-only ads are never charged.", "version": "1.0", "x-build-id": "WjIVahcSzzvwI0LDV" }, "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": "Keywords or advertiser page names to search, e.g. [\"fitness app\"] or [\"Nike\"] — start here if you have no ad IDs; each keyword returns the ads currently running in the country below, already transcribed. Keywords that match nothing ship as clearly-labelled rows and are never charged. What matches: an advertiser's page name, spelled as it appears on their Facebook page — `Nike`, `Acme Fitness`, `Rival Gym App` — or words that appear in the ads themselves, like `fitness app`. A website address (`nike.com`) is not a page name and finds nothing; a single ad's ID or link belongs in \"Ad Library links\" (`adLibraryUrls`), not here. The country below is part of the match, so an advertiser running ads in one market only needs that country set. 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. 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" } }, "country": { "title": "Country", "type": "string", "description": "Which country's Ad Library to search. The two-letter code (US, GB, DE, IN, 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. It scopes every search this run makes: search keywords AND any advertiser Ad Library PAGE link you paste. A page link's own country is not read — set it here. Ad links, dataset rows and video URLs name one ad each, so this does not apply to them.", "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, "type": "integer", "description": "How many ads each search keyword 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 }, "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). Links it can't resolve — removed ads, or a temporary block — ship as clearly-labelled rows and are never charged. The actor finds the ad's video for you. 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.", "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; they expire within hours to days. An ordinary Facebook video, reel or fb.watch link is not an ad-library link: paste it into steadyfetch/media-transcriber, field urls. Any other host's file goes there too. (Ad Library links pasted here are handled for you: an ad link is resolved, an advertiser's page link is read as a search of that page.) A file on any other host (your own storage, a CDN, a signed link) is not read here — pass it to our media transcriber (apify.com/steadyfetch/media-transcriber) and paste the link into its \"Media URLs\" (urls) field.", "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 never charged. OFF: image ads pass through uncharged 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 an uncharged `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 uncharged.", "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-`, so you can inspect or clear it any time. Leave empty for a one-off run — your account's memory of delivered ads still applies." }, "newAdsOnly": { "title": "New ads only", "type": "boolean", "description": "OFF (default): every ad runs as usual; an ad your account already has comes back from the earlier run, not charged (`repeat: true`), and every row carries `isNew` / `firstSeenAt`. ON: ads already on your watchlist — or, with no list name, already delivered to your account — 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 counts (a delivered transcript, image text or on-screen text, or a final uncharged 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 — does not, so the next run tries it again.", "default": false }, "maxAds": { "title": "Max ads to process", "minimum": 1, "type": "integer", "description": "Safety cap on how many ads to transcribe in one run. Up to 10,000 per run; ask for a bigger number and the run continues at 10,000, with one uncharged row saying so. 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 }, "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 } } } } } } } } } }