{ "openapi": "3.0.1", "info": { "title": "Ad Library Video Transcripts & Hooks: TikTok, Facebook, Google", "description": "Get transcripts and AI breakdowns of competitors' video ads from the TikTok Ad Library, Facebook/Instagram (Meta) Ad Library and Google Ads Transparency Center: hook, hook type, angle, offer, CTA, persona, script structure. Find winning ads and build a swipe file.", "version": "0.1", "x-build-id": "48hoBCTzprhrwaDDr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/zephyrous_lampshade~ad-library-video-transcripts/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-zephyrous_lampshade-ad-library-video-transcripts", "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/zephyrous_lampshade~ad-library-video-transcripts/runs": { "post": { "operationId": "runs-sync-zephyrous_lampshade-ad-library-video-transcripts", "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/zephyrous_lampshade~ad-library-video-transcripts/run-sync": { "post": { "operationId": "run-sync-zephyrous_lampshade-ad-library-video-transcripts", "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": { "sources": { "title": "Ad libraries", "type": "array", "description": "Which public ad libraries to search. TikTok = TikTok Ad Library (EU DSA transparency), Google = Google Ads Transparency Center (YouTube/Display video ads), Meta = Meta Ad Library (Facebook & Instagram; needs a residential proxy, which is selected automatically). Sources implied by Start URLs are added automatically.", "items": { "type": "string", "enum": [ "tiktok", "google", "meta" ], "enumTitles": [ "TikTok Ad Library", "Google Ads Transparency Center", "Meta Ad Library (Facebook & Instagram)" ] }, "default": [ "tiktok" ] }, "query": { "title": "Keyword", "type": "string", "description": "Search term, e.g. a product category (\"protein powder\"), a brand or a topic. Leave empty if you use Advertiser or Start URLs. If Query, Advertiser and Start URLs are all empty, a small demo search runs (TikTok, \"skincare\", 5 ads)." }, "advertiser": { "title": "Advertiser", "type": "string", "description": "Optional advertiser name or ID to restrict results to one competitor (e.g. \"Nike\" or a Google advertiser ID like AR0123...)." }, "startUrls": { "title": "Start URLs (ad library links)", "type": "array", "description": "Optional. Paste search, advertiser or single-ad URLs from library.tiktok.com, adstransparency.google.com or facebook.com/ads/library. The matching source is detected from the URL.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2), e.g. DE, FR, IT, ES, NL, PL, SE. The TikTok Ad Library only covers EU/EEA countries (+CH, UK). Use \"ALL\" where supported (Meta, Google).", "default": "DE" }, "maxAdsPerSource": { "title": "Max video ads per library", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of video ads to collect from each selected ad library (default 10). You are charged per ad (about $0.033 for a fully transcribed and analyzed ad), so start small.", "default": 10 }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD)." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this date (YYYY-MM-DD)." }, "activeOnly": { "title": "Only currently active ads", "type": "boolean", "description": "Skip ads that are no longer running. Long-running active ads are usually the winners.", "default": false }, "transcribe": { "title": "Transcribe videos", "type": "boolean", "description": "Download each video and transcribe the voice-over with Whisper (multilingual, auto language detection). Charged only when a transcript is produced.", "default": true }, "aiAnalysis": { "title": "AI hook & script analysis", "type": "boolean", "description": "Run an LLM on each transcript to extract hook, hook type, angle, offer, CTA, target persona, script structure and a summary. Requires transcription. Charged only on success.", "default": true }, "outputLanguage": { "title": "Analysis language", "enum": [ "original", "en", "de" ], "type": "string", "description": "Language of the AI analysis fields. The transcript itself always stays in the original spoken language.", "default": "original" }, "maxVideoSeconds": { "title": "Max seconds transcribed per video", "minimum": 5, "maximum": 600, "type": "integer", "description": "Only the first N seconds of each video are transcribed. Hooks live in the first 3 seconds, most ads are under 60 s.", "default": 180 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy is used by default. The Meta Ad Library blocks datacenter IPs, so the Meta source automatically uses the RESIDENTIAL proxy group (you don't need to change anything). Custom proxy URLs are used as-is for all sources.", "default": { "useApifyProxy": 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 }, "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 } } } } } } } } } }