{ "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.3", "x-build-id": "9lkhIRguYimEwtneM" }, "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 (with \"Stop on the first refusal\" on, every worker shares the run's one 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. The Advanced section below changes how refusals are handled.", "default": { "useApifyProxy": true } }, "stopOnFirstRefusal": { "title": "Stop on the first refusal", "type": "boolean", "description": "Warning, fewer results. The first time Google refuses a request (HTTP 403 or 429, any redirect, its \"unusual traffic\" page, an answer that is not Google's data, or an empty answer where Google promised more ads), the run stops: that request is not retried, no other IP is tried and no residential IP is ever used (a RESIDENTIAL group selected in the proxy settings is replaced by the Apify datacenter proxy for the run). The whole run uses one proxy session (one IP), never rotates and sends one request at a time (Parallel advertisers is 1), so nothing else is in flight when a refusal arrives. Creatives already read are still delivered and charged as creatives; their decode stops there and is charged only if it had already added data; the refusal costs nothing. Apify's shared datacenter pool includes IPs Google already refuses: it depends heavily on the hour: on 2026-10-22 in the morning 1 of 25 strict test runs on Apify datacenter stopped, and in the afternoon 21 of 23 stopped on their very first request (Google sent 12 of 12 fresh datacenter sessions to its unusual traffic page at that hour), while runs with the switch off still finished by moving to fresh sessions. Best for a few single creative links. Server errors and network timeouts are still retried, at most three times, on the same IP.", "default": false }, "disableResidentialFallback": { "title": "Disable residential fallback", "type": "boolean", "description": "Warning, more refused advertisers. Keeps an Apify datacenter run on datacenter IPs: when Google keeps refusing the datacenter pool, the Actor still moves to fresh datacenter sessions but never to Apify residential IPs. Rendering files (YouTube ids, rendered copy) come over datacenter in every mode, with or without this switch. No effect with the RESIDENTIAL group, custom proxy URLs or the proxy turned off.", "default": false }, "directCreativeLookup": { "title": "Look up pasted creative links directly", "type": "boolean", "description": "Warning, some fields empty. For single creative links (adstransparency.google.com/advertiser/AR.../creative/CR...): read the creative with one detail request instead of paging the advertiser's ad list until it turns up, two or three requests per link in all. In this mode firstShown, daysServed and advertiserVerified are empty (Google's detail does not carry them), previewUrl is the detail's preview link, and an HTML5 ad has no static imageUrl. Applies only without a region, platform, political topic or \"shown before\" filter; with one of those the link is paged as usual and the run summary says so. This listing preselects the YouTube platform: send an empty Platforms list to look links up directly.", "default": false } } }, "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 } } } } } } } } } }