# Facebook Ads Transcript Scraper (`automation-lab/facebook-ads-transcript-scraper`) Actor Extract Meta/Facebook Ads Library creative copy, video URLs, and transcript/subtitle fields exposed for public ads. - **URL**: https://apify.com/automation-lab/facebook-ads-transcript-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Social media - **Stats:** 2 total users, 1 monthly users, 83.3% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Facebook Ads Transcript Scraper Extract competitor Meta/Facebook Ad Library creative copy, media URLs, and transcript/subtitle fields when Meta exposes them publicly. Use this actor to turn Facebook ad research into structured rows for creative intelligence, hook analysis, ad swipe files, and downstream transcription workflows. ### What does Facebook Ads Transcript Scraper do? Facebook Ads Transcript Scraper searches public Meta Ads Library pages and saves one dataset row per ad creative. It captures: - ๐ŸŽฌ Video ad URLs and preview images - ๐Ÿ“ Creative body copy and headlines - ๐Ÿท๏ธ Advertiser/page metadata - ๐Ÿ”— Landing page URLs and calls to action - ๐Ÿงพ Transcript, subtitle, closed-caption, speech, or voiceover fields when present - ๐Ÿงช Diagnostics explaining whether transcript-like data was exposed The actor is intentionally focused on creative analysis instead of broad political-ad archiving. ### Who is it for? Performance marketers use it to monitor competitor hooks and offers. Creative strategists use it to build swipe files from live Facebook and Instagram ads. Agencies use it to compare messaging across client categories. Growth teams use it to discover videos that should be transcribed or reviewed by an editor. Researchers use it to export public ad metadata without manually opening every ad card. ### Why use this actor? Meta Ads Library is public, but it is difficult to export repeatably. This actor handles browser loading, proxy sessions, result normalization, and dataset output. It also separates true transcript availability from regular ad copy, so you know which creatives need external ASR. ### Important transcript caveat The actor does not invent audio transcripts. It extracts transcript/subtitle/closed-caption/speech/voiceover fields only when Meta exposes them in the public Ad Library response. If Meta only exposes the video URL and ad copy, the row will contain `transcriptAvailable=false`. You can still use the `videoUrls` field to pass videos into a separate transcription workflow. ### How much does it cost to extract Facebook ad transcripts? Pricing uses pay per event. - Start event: small one-time run fee - Item event: charged per saved ad row The default prefill is intentionally small so first runs stay cheap. Final tiered prices are calculated from cloud validation costs before QA handoff. ### Input options You can provide one or more of these inputs: - `searchQueries` โ€” keyword searches such as brand names, products, or hooks - `adsLibraryUrls` โ€” public Meta Ads Library result or detail URLs - `adArchiveIds` โ€” known numeric ad archive IDs ### Search filters The actor supports common Meta Ads Library filters: - `country` - `activeStatus` - `mediaType` - `maxAds` - `requireTranscript` Use `mediaType=video` when your goal is transcript discovery. ### Example input ```json { "searchQueries": ["fitness app"], "country": "US", "activeStatus": "all", "mediaType": "video", "maxAds": 25, "requireTranscript": false } ```` ### Example output fields Each dataset row may include: | Field | Description | |---|---| | `adArchiveId` | Meta Ad Library ID | | `pageName` | Advertiser or Facebook page name | | `creativeText` | Main ad body copy | | `title` | Headline or card title | | `videoUrls` | Public video URLs found in the response | | `transcriptAvailable` | Whether transcript-like fields were exposed | | `transcriptText` | Extracted transcript/subtitle text when available | | `diagnostics` | Notes about extraction and missing transcript fields | ### Output quality Rows are deduplicated by ad archive ID. Dates are normalized to ISO date strings. Arrays are used for media URLs because carousel/video ads can expose multiple assets. Null values mean Meta did not expose that field for the specific ad. ### How to use it 1. Open the actor on Apify. 2. Enter competitor keywords, Ads Library URLs, or ad archive IDs. 3. Keep `maxAds` small for the first run. 4. Run the actor. 5. Export the dataset as JSON, CSV, Excel, or via API. 6. Filter rows where `transcriptAvailable=true` for transcript-ready creatives. 7. Send rows with only `videoUrls` to your ASR pipeline if needed. ### Tips for better results Use specific brand or product keywords. Use `activeStatus=active` for current market research. Use `activeStatus=all` for historical creative analysis. Use `mediaType=video` for transcript workflows. Disable `requireTranscript` if you also want video URLs and creative copy. Enable `requireTranscript` only when you need a transcript-only dataset. ### Integrations Use this actor with: - Google Sheets for competitor swipe files - Airtable for creative review boards - Slack alerts for new competitor ads - BI dashboards for messaging trends - Whisper or another ASR actor for videos without exposed transcripts - LLM tools for hook, offer, and CTA classification ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/facebook-ads-transcript-scraper').call({ searchQueries: ['fitness app'], country: 'US', mediaType: 'video', maxAds: 10 }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('automation-lab/facebook-ads-transcript-scraper').call(run_input={ 'searchQueries': ['fitness app'], 'country': 'US', 'mediaType': 'video', 'maxAds': 10, }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~facebook-ads-transcript-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"searchQueries":["fitness app"],"country":"US","mediaType":"video","maxAds":10}' ``` ### MCP usage Connect Apify MCP with this actor enabled: ```bash claude mcp add apify-facebook-ads-transcripts https://mcp.apify.com/?tools=automation-lab/facebook-ads-transcript-scraper ``` Claude Desktop JSON configuration: ```json { "mcpServers": { "apify-facebook-ads-transcripts": { "url": "https://mcp.apify.com/?tools=automation-lab/facebook-ads-transcript-scraper" } } } ``` Example prompts: - "Find active video ads for meal prep apps and summarize the hooks." - "Export Facebook ad video URLs for this competitor keyword." - "Show only ads where transcriptAvailable is true." ### Legality and ethical use This actor extracts publicly available Meta Ads Library data. Respect Meta terms, privacy rules, and local laws. Do not use scraped data for harassment, discrimination, or unlawful profiling. ### FAQ #### Does it always return a transcript? No. Meta does not expose transcript-like fields for every video ad. The actor returns `transcriptAvailable=false` when only video URLs and creative copy are available. #### Can I use the video URL with another transcription tool? Yes. Use `videoUrls` for downstream ASR workflows when Meta does not expose transcript text directly. ### Troubleshooting: no results If a query returns no rows, try a broader keyword, a different country, or `activeStatus=all`. Facebook may also temporarily block or throttle a session. ### Troubleshooting: no transcripts Many video ads expose only the video URL and ad copy. That is normal. Use `transcriptAvailable` and `diagnostics.extractionNotes` to understand what happened. ### Related scrapers Related automation-lab actors: - https://apify.com/automation-lab/facebook-ads-library - https://apify.com/automation-lab/meta-ad-library-page-resolver - https://apify.com/automation-lab/google-ads-transparency-center-scraper - https://apify.com/automation-lab/pinterest-ads-library-scraper ### Best practices Start with 10 to 25 ads. Validate output fields. Increase limits only after confirming the query returns useful creatives. Run separate jobs for separate competitors so datasets stay easy to compare. ### Data retention Apify stores run datasets according to your account settings. Export or integrate important results into your own systems. ### Support If a public Ads Library URL fails repeatedly, include the run ID and input when reporting the issue. ### Changelog Initial version: keyword, Ads Library URL, and ad archive ID inputs with creative metadata, media URLs, transcript availability flags, and diagnostics. # Actor input Schema ## `searchQueries` (type: `array`): Keywords to search in Meta Ads Library. Use brand names, products, hooks, or competitor topics. ## `adsLibraryUrls` (type: `array`): Paste public facebook.com/ads/library search result URLs or ad detail URLs. ## `adArchiveIds` (type: `array`): Known Meta Ad Library archive IDs to inspect directly. ## `country` (type: `string`): Meta Ad Library country code used for keyword searches and proxy geolocation. ## `activeStatus` (type: `string`): Filter active, inactive, or all ads. ## `mediaType` (type: `string`): Video is the best default for transcript discovery. ## `maxAds` (type: `integer`): Maximum ad records to emit across all inputs. Keep small for first tests; raise for batch exports. ## `requireTranscript` (type: `boolean`): When enabled, ads without exposed transcript/caption fields are skipped. ## `includeRawDiagnostics` (type: `boolean`): Reserved for compatibility; output always includes concise extraction diagnostics. ## Actor input object example ```json { "searchQueries": [ "fitness app" ], "adsLibraryUrls": [], "adArchiveIds": [], "country": "US", "activeStatus": "all", "mediaType": "video", "maxAds": 10, "requireTranscript": false, "includeRawDiagnostics": true } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchQueries": [ "fitness app" ], "adsLibraryUrls": [], "adArchiveIds": [], "country": "US", "activeStatus": "all", "mediaType": "video", "maxAds": 10, "requireTranscript": false, "includeRawDiagnostics": true }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/facebook-ads-transcript-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchQueries": ["fitness app"], "adsLibraryUrls": [], "adArchiveIds": [], "country": "US", "activeStatus": "all", "mediaType": "video", "maxAds": 10, "requireTranscript": False, "includeRawDiagnostics": True, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/facebook-ads-transcript-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQueries": [ "fitness app" ], "adsLibraryUrls": [], "adArchiveIds": [], "country": "US", "activeStatus": "all", "mediaType": "video", "maxAds": 10, "requireTranscript": false, "includeRawDiagnostics": true }' | apify call automation-lab/facebook-ads-transcript-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/facebook-ads-transcript-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Transcript Scraper", "description": "Extract Meta/Facebook Ads Library creative copy, video URLs, and transcript/subtitle fields exposed for public ads.", "version": "0.1", "x-build-id": "rmCMwTleOr28V6mr0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~facebook-ads-transcript-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-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/automation-lab~facebook-ads-transcript-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-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/automation-lab~facebook-ads-transcript-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-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", "type": "array", "description": "Keywords to search in Meta Ads Library. Use brand names, products, hooks, or competitor topics.", "items": { "type": "string" } }, "adsLibraryUrls": { "title": "Meta Ads Library URLs", "type": "array", "description": "Paste public facebook.com/ads/library search result URLs or ad detail URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "adArchiveIds": { "title": "Ad archive IDs", "type": "array", "description": "Known Meta Ad Library archive IDs to inspect directly.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "US", "GB", "CA", "AU", "DE", "FR", "IT", "ES", "BR", "IN", "ALL" ], "type": "string", "description": "Meta Ad Library country code used for keyword searches and proxy geolocation.", "default": "US" }, "activeStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Filter active, inactive, or all ads.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "video", "all", "image_and_meme" ], "type": "string", "description": "Video is the best default for transcript discovery.", "default": "video" }, "maxAds": { "title": "Maximum ads", "minimum": 1, "maximum": 250, "type": "integer", "description": "Maximum ad records to emit across all inputs. Keep small for first tests; raise for batch exports.", "default": 25 }, "requireTranscript": { "title": "Only save ads with transcripts", "type": "boolean", "description": "When enabled, ads without exposed transcript/caption fields are skipped.", "default": false }, "includeRawDiagnostics": { "title": "Include diagnostics", "type": "boolean", "description": "Reserved for compatibility; output always includes concise extraction diagnostics.", "default": true } } }, "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 } } } } } } } } } } ```