{ "openapi": "3.0.1", "info": { "title": "Google Ads Monitor — Competitor Ads, New Ads Only, Full Ad Copy", "description": "Track competitors' Google ads from the Ads Transparency Center. Monitor mode returns only ads Google first showed since your last run. Text-ad copy read by OCR, video ad copy, landing URLs, regions. Flat schema, never null. Built for pipelines and AI agents.", "version": "0.1", "x-build-id": "3uYDQwpFq6Ca6quc2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sumitr_mardy~google-ads-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sumitr_mardy-google-ads-monitor", "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/sumitr_mardy~google-ads-monitor/runs": { "post": { "operationId": "runs-sync-sumitr_mardy-google-ads-monitor", "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/sumitr_mardy~google-ads-monitor/run-sync": { "post": { "operationId": "run-sync-sumitr_mardy-google-ads-monitor", "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", "required": [ "targets" ], "properties": { "targets": { "title": "Competitors to track", "type": "array", "description": "Competitors to check, one per item: a domain (\"hubspot.com\"), a Google advertiser ID (\"AR10072600183532683265\"), or a Google Ads Transparency Center URL (advertiser, creative or domain search). A domain finds every advertiser whose ads land on it, resellers and agencies included; every output record names its advertiser. Example: [\"hubspot.com\", \"AR10072600183532683265\"].", "items": { "type": "string" } }, "mode": { "title": "Mode", "enum": [ "monitor", "all" ], "type": "string", "description": "\"monitor\" (default): only ads Google first showed since the previous run for each target, judged by Google's own first-shown date; built for daily or hourly schedules, and a target's first run looks back lookbackDays. \"all\": the target's ads, most recently shown first, up to maxAdsPerTarget; use it for a one-off look at what a competitor is running.", "default": "monitor" }, "region": { "title": "Region", "pattern": "^([A-Za-z]{2}|[Aa]nywhere)$", "type": "string", "description": "Two-letter ISO country code (US, GB, DE, JP, VN...) to see only ads served in that country, or \"anywhere\" for all countries. A region inside a pasted Transparency Center URL takes precedence.", "default": "anywhere" }, "lookbackDays": { "title": "Lookback days (first monitor run)", "minimum": 1, "maximum": 365, "type": "integer", "description": "Monitor mode only: how many days back the FIRST run for a target reaches. Later runs start where the previous run ended, so they return only what is new.", "default": 7 }, "maxAdsPerTarget": { "title": "Max ads per target (All mode)", "minimum": 1, "type": "integer", "description": "All mode only: how many ads to return per target, most recently shown first. Monitor mode always returns every new ad. For a quick answer to an AI agent, keep it small (10-25): reading ad copy takes about a second per ad.", "default": 100 }, "adCopy": { "title": "Read ad copy", "type": "boolean", "description": "Read the ad copy: text ads from Google's archived screenshot (OCR); video and some image ads from their own data (headline, description, call to action, landing URL, YouTube link). Turn off for much faster runs when only IDs, dates and countries are needed.", "default": true }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Monitor mode only. Keeps separate schedules apart: a daily and a weekly schedule on the same targets need different names, or each will treat the other's runs as its own. Any short name.", "default": "default" }, "maxPagesPerCheck": { "title": "Max pages per target", "minimum": 1, "type": "integer", "description": "Safety cap on how deep one target's listing is read (40 ads per page). Very large advertisers show thousands of ads a day; the run log and SUMMARY say when a target hit the cap.", "default": 100 }, "concurrency": { "title": "Targets in parallel", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many targets are checked side by side. Pages of a single target are always read in order.", "default": 4 }, "residentialFallback": { "title": "Switch to residential when blocked", "type": "boolean", "description": "When Google keeps blocking the proxy for one target, switch that target to Apify residential proxy for the rest of the run. Included in the price: no extra charge to you.", "default": true }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy (datacenter) by default; the Actor changes IP by itself when Google pushes back. You normally do not need to change this.", "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 } } } } } } } } } }