{ "openapi": "3.0.1", "info": { "title": "YouTube Ads Scraper - Video Ads by Advertiser", "description": "Find the video ads any brand runs on YouTube through the Google Ads Transparency Center: YouTube video id and watch URL, thumbnail, companion headline and description, first and last shown dates, days running and EU impression bands per surface. Filter by region and date. Pay per creative.", "version": "0.2", "x-build-id": "0H0lo6m9nLcTOeIx4" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation_craft~youtube-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation_craft-youtube-ads-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_craft~youtube-ads-scraper/runs": { "post": { "operationId": "runs-sync-automation_craft-youtube-ads-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_craft~youtube-ads-scraper/run-sync": { "post": { "operationId": "run-sync-automation_craft-youtube-ads-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": { "advertisers": { "title": "Advertisers (names, domains, AR ids or URLs)", "type": "array", "description": "One entry per advertiser. Accepts a website domain (\"nike.com\", the most exact), an advertiser name (\"Nike, Inc.\", resolved through the Transparency Center's own suggestions), an AR id (\"AR16735076323512287233\") or a pasted adstransparency.google.com URL (advertiser page, ?domain= search, or a single creative link). Case, spaces, http and www do not matter.", "items": { "type": "string" } }, "region": { "title": "Region", "enum": [ "ANYWHERE", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "IC", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string", "description": "Only creatives shown in this region (the Transparency Center \"region\" filter). \"Anywhere\" searches every region. API callers send the upper case ISO code (US, GB, DE) or ANYWHERE.", "default": "ANYWHERE" }, "platforms": { "title": "Platforms", "type": "array", "description": "Where the ad ran: Google Search, YouTube, Shopping, Maps or Google Play. Leave empty for every platform. This listing preselects YouTube.", "items": { "type": "string", "enum": [ "search", "youtube", "shopping", "maps", "play" ], "enumTitles": [ "Google Search", "YouTube", "Google Shopping", "Google Maps", "Google Play" ] } }, "formats": { "title": "Formats", "type": "array", "description": "Text, image or video creatives. Leave empty for all three. This listing preselects video.", "items": { "type": "string", "enum": [ "text", "image", "video" ], "enumTitles": [ "Text", "Image", "Video" ] } }, "lastShownAfter": { "title": "Shown after (YYYY-MM-DD)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only creatives that were shown on or after this date (the Transparency Center date filter). Leave empty for no lower bound." }, "lastShownBefore": { "title": "Shown before (YYYY-MM-DD)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only creatives that were shown on or before this date. Leave empty for no upper bound." }, "topic": { "title": "Ad topic", "enum": [ "all", "political" ], "type": "string", "description": "All ads, or only political ads (Google's political report: exact match counts, spend and impression ranges, audience selection). A political pull without an advertiser needs a region.", "default": "all" }, "sort": { "title": "Sort", "enum": [ "lastShown", "impressions" ], "type": "string", "description": "Order in which Google returns creatives, which decides which ones fit under your cap: most recently shown first (default) or highest impressions first.", "default": "lastShown" }, "maxCreativesPerAdvertiser": { "title": "Max creatives per advertiser", "minimum": 1, "type": "integer", "description": "Stop each advertiser after this many delivered creatives. Google returns 100 per page; large advertisers hold tens of thousands.", "default": 100 }, "maxTotal": { "title": "Max creatives per run", "minimum": 1, "type": "integer", "description": "Hard cap on delivered creatives for the whole run, across all advertisers.", "default": 1000 }, "decodeCreatives": { "title": "Decode creatives", "type": "boolean", "description": "Fetch each creative's detail and rendering and decode it: headline, description, call to action, display and landing URLs, product and merchant, YouTube video id and playback URLs, store locations, served countries, EU impression bands per region and surface, topic and payer name. $0.30 per 1,000, charged only when the decode returned data. Off = metadata, preview and image URLs only.", "default": false }, "ocrImageOnlyText": { "title": "Read image-only text ads (OCR)", "type": "boolean", "description": "About a quarter of text ads are published by Google only as a rendered image. With this on (and \"Decode creatives\" on), the Actor reads the headline, description, display URL and sitelinks out of that image with an open source OCR engine running inside the Actor, no key, no third party. $0.50 per 1,000, charged only when a headline was read; the row carries the recognised text and a confidence score. Measured on 66 live renders: the headline is recovered on 92 percent of Latin-script renders, Japanese at about 90 percent per character. Needs a run memory of 512 MB or more (set it in the run options); with less, rows are delivered without OCR and nothing is charged for it.", "default": false }, "memoryName": { "title": "Memory name (return only new creatives)", "type": "string", "description": "Give a name and the Actor remembers every creative it delivered under it. Later runs with the same name return only creatives you have not received yet; known creatives are skipped and never charged again. Ideal for a scheduled competitor watch." }, "emitKnown": { "title": "Also return known creatives (free)", "type": "boolean", "description": "With a memory name: also deliver creatives the memory already knows, marked isNew: false and never charged.", "default": false }, "resetMemory": { "title": "Reset the memory", "type": "boolean", "description": "Forget every creative remembered under the memory name before this run.", "default": false }, "concurrency": { "title": "Parallel advertisers", "minimum": 1, "maximum": 8, "type": "integer", "description": "How many advertisers are paged at the same time. Each worker holds its own rotating proxy session.", "default": 3 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify datacenter proxy by default (near free); the Actor rotates sessions itself and falls back to Apify residential for the small RPC calls when Google refuses the datacenter pool. Selecting RESIDENTIAL here routes every call residential.", "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 } } } } } } } } } }