{ "openapi": "3.0.1", "info": { "title": "Competitor Ad Monitoring & Creative Changes", "description": "Monitor competitor ad changes across compatible Meta, Google, LinkedIn and TikTok datasets. Detect new ads, creative updates, landing-page changes and ad lifecycle events with source-health evidence. Bring your own datasets or source Actors. Unofficial beta.", "version": "0.2", "x-build-id": "RXRpelVNKBsrYFl20" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dekaz~cross-channel-ad-intelligence-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dekaz-cross-channel-ad-intelligence-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/dekaz~cross-channel-ad-intelligence-monitor/runs": { "post": { "operationId": "runs-sync-dekaz-cross-channel-ad-intelligence-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/dekaz~cross-channel-ad-intelligence-monitor/run-sync": { "post": { "operationId": "run-sync-dekaz-cross-channel-ad-intelligence-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": [ "monitorId", "targets", "platforms" ], "properties": { "monitorId": { "title": "Monitor ID", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,79}$", "minLength": 3, "maxLength": 80, "type": "string", "description": "Stable history identifier. Reuse it for comparable scheduled scans. Changing country, identity or source filters resets the affected comparison scope to avoid false alerts.", "default": "my-competitor-monitor" }, "targets": { "title": "Competitors", "minItems": 1, "maxItems": 100, "type": "array", "description": "Brands or advertisers to monitor. Domain is required; add stable platform identifiers to prevent ambiguous matches.", "items": { "type": "object", "properties": { "id": { "title": "Target ID", "description": "Stable internal identifier. Do not change it between runs.", "type": "string", "editor": "textfield", "minLength": 1, "maxLength": 80 }, "name": { "title": "Target name", "description": "Human-readable brand or advertiser name.", "type": "string", "editor": "textfield", "minLength": 1, "maxLength": 160 }, "domain": { "title": "Primary domain", "description": "Canonical advertiser domain without a path.", "type": "string", "editor": "textfield", "minLength": 3, "maxLength": 253 }, "metaPageId": { "title": "Meta Page ID", "description": "Stable Meta Page identifier when known.", "type": "string", "editor": "textfield", "maxLength": 160 }, "metaPageUrl": { "title": "Meta Page URL", "description": "Public URL of the advertiser's Meta Page.", "type": "string", "editor": "textfield", "maxLength": 2048 }, "metaAdLibraryUrl": { "title": "Meta Ad Library URL", "description": "Public Meta Ad Library URL that identifies this advertiser.", "type": "string", "editor": "textfield", "maxLength": 4096 }, "googleAdvertiserId": { "title": "Google advertiser ID", "description": "Stable advertiser ID from the Google Ads Transparency Center.", "type": "string", "editor": "textfield", "maxLength": 160 }, "googleAdvertiserUrl": { "title": "Google transparency URL", "description": "Public Google Ads Transparency Center advertiser URL.", "type": "string", "editor": "textfield", "maxLength": 4096 }, "linkedinCompanyId": { "title": "LinkedIn company ID", "description": "Stable LinkedIn company or advertiser identifier when known.", "type": "string", "editor": "textfield", "maxLength": 160 }, "linkedinAdLibraryUrl": { "title": "LinkedIn Ad Library URL", "description": "Public LinkedIn Ad Library URL that identifies this advertiser.", "type": "string", "editor": "textfield", "maxLength": 4096 }, "tiktokAdvertiserId": { "title": "TikTok advertiser ID", "description": "Stable advertiser identifier from the configured TikTok source.", "type": "string", "editor": "textfield", "maxLength": 160 }, "tiktokAdvertiserName": { "title": "TikTok advertiser name", "description": "Exact advertiser name used only when a stable ID is unavailable.", "type": "string", "editor": "textfield", "maxLength": 160 } }, "required": [ "id", "name", "domain" ], "additionalProperties": false }, "default": [ { "id": "nike", "name": "Nike", "domain": "nike.com", "metaPageUrl": "https://www.facebook.com/nike", "googleAdvertiserId": "", "linkedinAdLibraryUrl": "", "tiktokAdvertiserName": "Nike" } ] }, "platforms": { "title": "Platforms", "minItems": 1, "uniqueItems": true, "type": "array", "description": "Sources to scan independently. A source failure never hides results from the others.", "items": { "type": "string", "enum": [ "META", "GOOGLE", "LINKEDIN", "TIKTOK" ], "enumTitles": [ "Meta Ads Library", "Google Ads Transparency", "LinkedIn Ad Library", "TikTok Commercial Content" ] }, "default": [ "META", "GOOGLE" ] }, "country": { "title": "Country", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Two-letter country code used for source queries and regional availability.", "default": "ES" }, "maxAdsPerTarget": { "title": "Maximum ads per competitor and platform", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Per-target/platform safety cap. A capped source is truncated: observed new/changed ads can be compared after the initial reference, but missing ads are never treated as inactive from this scan.", "default": 100 }, "missingScansBeforeInactive": { "title": "Complete missing scans before deactivation", "minimum": 2, "maximum": 10, "type": "integer", "description": "An ad must be absent from this many complete scans before it is confirmed inactive.", "default": 2 }, "providerMode": { "title": "Data provider mode", "enum": [ "AUTO", "EXTERNAL_ACTOR", "DATASET" ], "type": "string", "description": "DATASET reads selected datasets. AUTO prefers a selected dataset, then an explicitly configured source Actor or an unverified built-in candidate. EXTERNAL_ACTOR can incur separate charges. Inspect preflightOnly before collection.", "default": "AUTO" }, "metaSourceDataset": { "title": "Meta source dataset", "type": "string", "description": "Optional read-only dataset containing compatible Meta Ad Library source records." }, "googleSourceDataset": { "title": "Google source dataset", "type": "string", "description": "Optional read-only dataset containing compatible Google Ads Transparency source records." }, "linkedinSourceDataset": { "title": "LinkedIn source dataset", "type": "string", "description": "Optional read-only dataset containing compatible LinkedIn Ad Library source records." }, "tiktokSourceDataset": { "title": "TikTok source dataset", "type": "string", "description": "Optional read-only dataset containing compatible TikTok Commercial Content Library records. Creative Center records are treated as a separate, partial source." }, "sourceActorIds": { "title": "Bring-your-own source Actor IDs", "type": "object", "description": "Compatible source Actor overrides keyed by platform. Without an override, AUTO/EXTERNAL_ACTOR uses an unverified built-in candidate. Confirm permissions, build, input/output schema and price. Child Actors charge separately.", "properties": { "META": { "title": "Meta source Actor", "description": "Compatible Actor ID in username/name or ID form.", "type": "string", "editor": "textfield", "maxLength": 160 }, "GOOGLE": { "title": "Google source Actor", "description": "Compatible Actor ID in username/name or ID form.", "type": "string", "editor": "textfield", "maxLength": 160 }, "LINKEDIN": { "title": "LinkedIn source Actor", "description": "Compatible Actor ID in username/name or ID form.", "type": "string", "editor": "textfield", "maxLength": 160 }, "TIKTOK": { "title": "TikTok source Actor", "description": "Compatible Actor ID in username/name or ID form.", "type": "string", "editor": "textfield", "maxLength": 160 } }, "default": {}, "additionalProperties": false }, "sourceActorBuilds": { "title": "Source Actor build pins (optional)", "type": "object", "description": "Optional build tags or versions keyed by platform. Choose builds that exist and verify their permissions and schemas. Numeric version pins avoid silently following latest; a mutable tag can still change upstream. Changing a pin starts a fresh observation baseline.", "properties": { "META": { "title": "Meta source build", "type": "string", "editor": "textfield", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "minLength": 1, "maxLength": 64, "description": "Existing source Actor build tag or exact version. Verify this build on the selected provider before scheduling." }, "GOOGLE": { "title": "Google source build", "type": "string", "editor": "textfield", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "minLength": 1, "maxLength": 64, "description": "Existing source Actor build tag or exact version. Verify this build on the selected provider before scheduling." }, "LINKEDIN": { "title": "LinkedIn source build", "type": "string", "editor": "textfield", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "minLength": 1, "maxLength": 64, "description": "Existing source Actor build tag or exact version. Verify this build on the selected provider before scheduling." }, "TIKTOK": { "title": "TikTok source build", "type": "string", "editor": "textfield", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "minLength": 1, "maxLength": 64, "description": "Existing source Actor build tag or exact version. Verify this build on the selected provider before scheduling." } }, "default": {}, "additionalProperties": false }, "maxSourceChargeUsd": { "title": "Maximum charge per source Actor call", "minimum": 0.01, "maximum": 100, "type": "number", "description": "Hard cap applied to each paid child Actor call. Source Actor charges are paid from the current user's account.", "default": 1 }, "initialRunBehavior": { "title": "First run behavior", "enum": [ "BASELINE_ONLY", "EMIT_EXISTING_AS_NEW" ], "type": "string", "description": "Baseline only avoids reporting every existing ad as new on the first run.", "default": "BASELINE_ONLY" }, "includeLandingAnalysis": { "title": "Analyze landing pages", "type": "boolean", "description": "Fetch public landing pages with strict SSRF, redirect, size, MIME, and timeout limits.", "default": true }, "maxLandingPagesPerRun": { "title": "Maximum unique landing pages per run", "minimum": 1, "maximum": 100, "type": "integer", "description": "Global safety cap after URL deduplication. Ads beyond the cap are still normalized and analyzed without a landing snapshot.", "default": 25 }, "analysisMode": { "title": "Creative analysis", "enum": [ "OFF", "RULES" ], "type": "string", "description": "Rules mode extracts offers, CTA, hooks, and evidence without paid AI APIs.", "default": "RULES" }, "webhookUrl": { "title": "Optional alert webhook", "type": "string", "description": "HTTPS endpoint that receives signed change events after successful persistence." }, "webhookHmacSecret": { "title": "Webhook signing secret", "type": "string", "description": "Optional HMAC-SHA256 secret. It is never written to datasets or logs." }, "dryRun": { "title": "Dry run", "type": "boolean", "description": "Analyze without persisting monitor state, sending webhooks, or emitting this Actor's proposed custom charge events. Compatible child Actors can still incur their own charges; choose Dataset mode to avoid child Actor runs.", "default": false }, "maxTotalSourceChargeUsd": { "title": "Total reserved source-call budget per run", "minimum": 0, "maximum": 40000, "type": "number", "description": "Conservative total reservation across child source calls in this run, retained over restarts. Each reservation uses the call ceiling, not measured spend, and is not released when a source fails. Calls exceeding the remaining reservation are skipped. Zero blocks source calls. Excludes monitor charges, platform usage and taxes.", "default": 5 }, "preflightOnly": { "title": "Preview source selection and costs only", "type": "boolean", "description": "Write PREFLIGHT.json without launching source Actors, fetching landing pages, persisting monitor state, sending webhooks or charging this Actor custom events. Apify execution resources can still apply. Disable to collect data.", "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 } } } } } } } } } }