{ "openapi": "3.0.1", "info": { "title": "Ad Library Monitor: Competitor Ads on Google, Meta & TikTok", "description": "Watch competitors' ads in the public ad libraries of Google, Meta (Facebook, Instagram) and TikTok: new and stopped ads with first and last shown dates, text, links to creatives and landing pages. Only your Apify account needed.", "version": "0.2", "x-build-id": "U0YoM5J7AzDt4bF0N" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleanpull~ad-library-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleanpull-ad-library-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/cleanpull~ad-library-monitor/runs": { "post": { "operationId": "runs-sync-cleanpull-ad-library-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/cleanpull~ad-library-monitor/run-sync": { "post": { "operationId": "run-sync-cleanpull-ad-library-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", "properties": { "advertisers": { "title": "Advertisers", "type": "array", "description": "Brand names or domains, one per line. A name is matched to the platform's advertisers (Google: Allbirds → Allbirds Inc; Meta: the brand's pages; TikTok: its business accounts); a domain (brand.com) finds Google's ads that point to it and Meta and TikTok ads that mention it. Each line is checked on every platform chosen.", "items": { "type": "string" } }, "keywords": { "title": "Keywords", "type": "array", "description": "Optional. Words to find in ad text, one per line (Meta and TikTok; the Google library is searched by advertiser only). Every advertiser's ads that use them come back.", "items": { "type": "string" } }, "googleAdvertiserIds": { "title": "Google advertiser ids", "type": "array", "description": "Optional. Advertiser ids (AR…) or Ads Transparency Center addresses, for an exact advertiser.", "items": { "type": "string", "pattern": "AR\\d{10,}" } }, "metaPageIds": { "title": "Meta page ids", "type": "array", "description": "Optional. Facebook page ids, or Ad Library addresses with view_all_page_id=…, for an exact page.", "items": { "type": "string", "pattern": "^\\s*\\d{5,20}\\s*$|[?&](?:view_all_page_id|page_id|id)=\\d{5,20}" } }, "platforms": { "title": "Platforms", "minItems": 1, "type": "array", "description": "Where to look. Meta and TikTok are read from their public ad libraries through CleanPull's ad library service, at one library request per page of ads (30 Meta ads, 12 TikTok ads); Google is read directly.", "items": { "type": "string", "enum": [ "google", "meta", "tiktok" ], "enumTitles": [ "Google Ads Transparency Center (search, YouTube, display; any country)", "Meta Ad Library (Facebook, Instagram; any country)", "TikTok ads library (ads shown in the EU, the UK and Switzerland)" ] }, "default": [ "google", "meta", "tiktok" ] }, "countries": { "title": "Countries", "type": "array", "description": "Optional. Two-letter country codes (US, DE, GB), up to 5; each is read separately on Google and Meta. Empty: anywhere. TikTok's library covers the EU, the UK and Switzerland as a whole and is not narrowed by country.", "items": { "type": "string" } }, "activeOnly": { "title": "Active ads only", "type": "boolean", "description": "Only ads running now (Google: shown in the last 3 days; TikTok: in the last 7 days; Meta: its active flag). Off: stopped ads too (Meta lists stopped non-political ads only for the EU).", "default": true }, "maxAdsPerTarget": { "title": "Ads per watch item", "minimum": 1, "maximum": 1000, "type": "integer", "description": "The most ads read per watch item and platform each run. A check is charged per 100 ads read (1 up to 100, 2 up to 200), plus one library request per page of Meta or TikTok ads. Stops are confirmed only for watch items read in full.", "default": 100 }, "minDaysRunning": { "title": "Days running (at least)", "minimum": 1, "maximum": 3650, "type": "integer", "description": "Only ads that started at least this many days ago (35: proven ads, still running after five weeks). Meta and TikTok only: Meta is asked for these ads directly; every ad's start date is checked again before any row. Ads running fewer days, or without a start date, are left out and never charged (library requests are charged as usual). Google is read as before: its Ads Transparency Center has no keyword search. With Changes only, no ad is new (new ads started since the last run)." }, "oneRowPerAdvertiser": { "title": "One row per advertiser", "type": "boolean", "description": "Instead of a row per ad, one row per advertiser and watch item: name, page id, landing domain (the site most of its ads link to), ads kept, earliest start date, days running and a sample ad link. Ready to feed a store lookup. Each advertiser row is charged as one ad; change rows are left out.", "default": false }, "changesOnly": { "title": "Changes only", "type": "boolean", "description": "After the first run, return only new ads and confirmed stops (plus the ad rows of the new ads). The first run returns every ad as the baseline.", "default": false }, "monitorName": { "title": "Watchlist name", "type": "string", "description": "Runs with the same name share their memory of seen ads. Use a different name per watchlist.", "default": "default" }, "maxRunCostUsd": { "title": "Max cost per run (USD)", "minimum": 0.001, "maximum": 1000, "type": "number", "description": "Optional. The run stops before charging past this amount, for scheduled runs without a spending limit of their own. What was not read is read in full on the next run." }, "fields": { "title": "Fields", "type": "array", "description": "Optional. Only these fields in each row (recordType always stays), e.g. advertiser, adUrl, firstShown.", "items": { "type": "string" } }, "maxConcurrency": { "title": "Watch items at a time", "minimum": 1, "maximum": 2, "type": "integer", "description": "Watch items read at once. Requests to each platform are always one at a time and spaced.", "default": 2 } } }, "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 } } } } } } } } } }