{ "openapi": "3.0.1", "info": { "title": "AdPulse — Google Ads Competitor Intelligence", "description": "Competitive intelligence for Google Ads. Monitor competitors over time, detect evidence-backed creative changes, ad activity, format shifts, and actionable signals through dashboards, alerts, and structured outputs.", "version": "0.0", "x-build-id": "zQdLDYUTNYMbdQxZP" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/p90dro~adpulse/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-p90dro-adpulse", "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/p90dro~adpulse/runs": { "post": { "operationId": "runs-sync-p90dro-adpulse", "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/p90dro~adpulse/run-sync": { "post": { "operationId": "run-sync-p90dro-adpulse", "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": { "advertiserIds": { "title": "Competitor advertiser IDs", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Exact Google Ads Transparency advertiser IDs. Recommended for recurring monitoring because they keep history attached to the same advertiser. advertiserIds + competitor names may total at most 50 targets per run.", "items": { "type": "string" }, "default": [] }, "searchTerms": { "title": "Competitor names (optional)", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Competitor names to resolve when you do not know the advertiser ID. Exact IDs are safer for recurring monitoring; ambiguous matches fail instead of attaching history to the wrong advertiser. Combined with advertiser IDs, at most 50 targets are allowed.", "items": { "type": "string" }, "default": [] }, "region": { "title": "Market / region", "type": "string", "description": "Two-letter Google Ads Transparency country code, such as BR or US. Use 'anywhere' for an unfiltered market.", "default": "BR" }, "maxAds": { "title": "Creative limit per competitor", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum unique creatives collected per competitor in this run. Store release is intentionally capped at 100 creatives per competitor to keep the US$0.10 snapshot economics and source workload inside the accepted operating envelope. This is a source-work limit, not the number of billable competitor snapshots.", "default": 100 }, "mode": { "title": "Monitoring mode", "enum": [ "pulse", "reconciliation" ], "type": "string", "description": "Pulse is the normal low-cost recurring scan. Reconciliation is the stronger confirmation pass used when disappearance evidence needs a complete follow-up.", "default": "pulse" }, "stateNamespace": { "title": "Monitoring workspace", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "minLength": 1, "maxLength": 63, "type": "string", "description": "Stable lowercase workspace key for monitoring history. Reuse the same value for runs that belong to the same monitor; use a different value to isolate histories.", "default": "default" }, "proxyConfiguration": { "title": "Use Apify Proxy", "type": "object", "description": "Use Apify Proxy for more reliable source access. Recommended for Store runs; AdPulse rotates unhealthy source sessions without treating a failed fetch as an empty result." }, "strictSchema": { "title": "Fail safely on source schema changes", "type": "boolean", "description": "Recommended. Stops the run if Google's undocumented response shape changes in a way that could make the data unsafe to interpret.", "default": true }, "semanticEnrichment": { "title": "Semantic enrichment settings", "type": "object", "description": "Optional vision-based semantic analysis of eligible creative families. Disabled by default. If enabled, OPENAI_API_KEY must be configured as an Actor environment variable; secrets are never accepted in input or persisted to outputs.", "properties": { "enabled": { "title": "Enable semantic enrichment", "type": "boolean", "description": "Analyze eligible image-snapshot creative families with evidence-bound vision semantics.", "default": false }, "provider": { "title": "Provider", "type": "string", "description": "Stage 10 v1 supports OpenAI Responses API only.", "enum": [ "openai" ], "default": "openai" }, "model": { "title": "Model", "type": "string", "description": "OpenAI vision-capable Responses API model identifier.", "default": "gpt-5-mini" }, "maxFamiliesPerRun": { "title": "Maximum new families per run", "type": "integer", "description": "Cost guard. Cache hits do not consume this limit; only new exact families sent to the semantic provider count.", "minimum": 1, "maximum": 200, "default": 20 }, "imageDetail": { "title": "Image detail", "type": "string", "description": "Vision detail level passed to the provider.", "enum": [ "low", "auto", "high" ], "default": "auto" } }, "default": { "enabled": false, "provider": "openai", "model": "gpt-5-mini", "maxFamiliesPerRun": 20, "imageDetail": "auto" }, "additionalProperties": false }, "landingIntelligence": { "title": "Ad ↔ landing intelligence", "type": "object", "description": "Optionally resolve source-backed ad destinations and observe exact public landing pages when Google exposes a defensible final URL. Google ad click trackers are never requested.", "properties": { "enabled": { "title": "Enable ad ↔ landing intelligence", "type": "boolean", "default": false, "description": "Resolve destination evidence from Google creative details and observe exact public landing pages when the source exposes a direct final URL." }, "maxCreativeDetailsPerRun": { "title": "Maximum Google creative-detail lookups per run", "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Global per-run cost/reliability guard across all monitored targets. Stable creatives reuse cached destination evidence; eligible refresh work is distributed deterministically across targets." }, "maxPagesPerRun": { "title": "Maximum landing pages per run", "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Global maximum of unique exact landing URLs fetched for page-change observation across all monitored targets in one run." }, "pageTimeoutSeconds": { "title": "Landing page timeout (seconds)", "type": "integer", "minimum": 1, "maximum": 60, "default": 15, "description": "Bounded timeout for each direct landing-page request. Google ad click trackers are never requested." }, "maxHtmlChars": { "title": "Maximum HTML characters retained for parsing", "type": "integer", "minimum": 100000, "maximum": 2000000, "default": 1000000, "description": "Safety cap for static HTML parsing. Raw HTML is not persisted." }, "unavailableRetryRevisions": { "title": "Retry unavailable destination evidence after revisions", "type": "integer", "minimum": 1, "maximum": 100, "default": 7, "description": "Stable creatives whose destination could not be resolved are retried only after this many monitor revisions." } }, "default": { "enabled": false, "maxCreativeDetailsPerRun": 20, "maxPagesPerRun": 10, "pageTimeoutSeconds": 15, "maxHtmlChars": 1000000, "unavailableRetryRevisions": 7 }, "additionalProperties": false }, "monitoringPolicy": { "title": "Monitoring cadence", "type": "object", "description": "Intended monitoring cadence for pulse, periodic reconciliation, and follow-up after a one-observation MISSING watch. Apify schedules themselves remain platform-level.", "properties": { "pulseIntervalHours": { "title": "Pulse interval (hours)", "type": "integer", "description": "Routine low-cost monitoring cadence. Default: once every 24 hours.", "minimum": 1, "maximum": 720, "default": 24 }, "periodicReconciliationIntervalHours": { "title": "Periodic reconciliation interval (hours)", "type": "integer", "description": "Stronger confirmation cadence used to reconcile absence/state. Default: once every 7 days.", "minimum": 6, "maximum": 2160, "default": 168 }, "missingWatchReconciliationDelayHours": { "title": "Missing-watch follow-up delay (hours)", "type": "integer", "description": "When Stage 12 emits a non-deliverable MISSING watch, Stage 12B recommends a reconciliation after this delay. Default: 6 hours.", "minimum": 1, "maximum": 168, "default": 6 } }, "default": { "pulseIntervalHours": 24, "periodicReconciliationIntervalHours": 168, "missingWatchReconciliationDelayHours": 6 }, "additionalProperties": false }, "delivery": { "title": "Alert delivery", "type": "object", "description": "Outbox mode writes deterministic delivery payloads only. Webhook mode additionally sends deliveryRecommended=true messages to the HTTPS URL stored in the selected environment variable.", "properties": { "mode": { "title": "Delivery mode", "type": "string", "enum": [ "outbox", "webhook" ], "enumTitles": [ "Outbox only", "Webhook + outbox" ], "default": "outbox", "description": "Outbox writes versioned delivery payloads only. Webhook additionally sends eligible messages to the URL stored in the configured environment variable." }, "webhookEnvVar": { "title": "Webhook URL environment variable", "type": "string", "description": "Name of the environment variable containing the webhook URL. The URL itself is never accepted in Actor input or persisted in outputs.", "default": "ADPULSE_DELIVERY_WEBHOOK_URL", "pattern": "^[A-Z][A-Z0-9_]{2,63}$" }, "maxAttempts": { "title": "Webhook attempts", "type": "integer", "description": "Maximum bounded webhook attempts for transient network or retryable HTTP failures.", "minimum": 1, "maximum": 5, "default": 3 }, "timeoutSeconds": { "title": "Webhook timeout (seconds)", "type": "integer", "minimum": 1, "maximum": 60, "default": 10, "description": "Per-request webhook timeout in seconds." } }, "default": { "mode": "outbox", "webhookEnvVar": "ADPULSE_DELIVERY_WEBHOOK_URL", "maxAttempts": 3, "timeoutSeconds": 10 }, "additionalProperties": false }, "economicsBenchmark": { "title": "Private economics benchmark", "type": "object", "description": "Internal cost-observability configuration retained for controlled owner benchmarks. Hidden from the Store form and disabled by default.", "properties": { "enabled": { "title": "Enable private economics telemetry", "type": "boolean", "description": "Reads a provisional current-run usage snapshot from the Apify Run API and writes Stage 15 economics artifacts. No billing event is charged.", "default": false }, "scenario": { "title": "Benchmark scenario", "type": "string", "description": "Label this run for the private benchmark matrix. Auto infers the common case; explicit labels are preferred for controlled acceptance runs.", "enum": [ "auto", "routine_warm_cache", "cold_monitor_state", "semantic_cold_cache", "semantic_warm_cache", "reconciliation", "scale_10", "scale_50", "resilience_observed", "custom" ], "enumTitles": [ "Auto", "Routine warm cache", "Cold monitor state", "Semantic cold cache", "Semantic warm cache", "Reconciliation", "Scale — 10 competitors", "Scale — 50 competitors", "Observed resilience / retries", "Custom" ], "default": "auto" }, "sampleGroup": { "title": "Benchmark sample group", "type": "string", "description": "Stable private experiment group used to keep cost samples comparable across runs.", "default": "stage15-private-ppe", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "minLength": 1, "maxLength": 63 } }, "default": { "enabled": false, "scenario": "auto", "sampleGroup": "stage15-private-ppe" }, "additionalProperties": false }, "crossPlatformSources": { "title": "Cross-platform source settings", "type": "object", "description": "Optional Meta Ad Library source mappings. Meta evidence is joined to a Google advertiser only through an explicit Google advertiser ID plus verified domain mapping.", "properties": { "metaAdsLibrary": { "title": "Meta Ad Library mappings", "type": "array", "description": "Explicit mappings from a Google advertiser target to public Meta Ad Library search evidence. Each mapping is fail-soft and cannot rewrite Google State/Diff truth.", "default": [], "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "googleAdvertiserId", "query", "advertiserDomain" ], "properties": { "googleAdvertiserId": { "type": "string", "title": "Google advertiser ID", "description": "Must exactly match one advertiserIds entry in this run." }, "query": { "type": "string", "title": "Meta public-library search query", "description": "Brand/advertiser query used on the public Meta Ad Library search surface.", "minLength": 1, "maxLength": 100 }, "advertiserDomain": { "type": "string", "title": "Verified advertiser domain", "description": "Only Meta ads whose exact landing or display domain matches this domain/subdomain are admitted to the same advertiser entity." }, "country": { "type": "string", "title": "Meta market", "description": "Two-letter Meta Ad Library country code or ALL. Defaults to the AdPulse region.", "default": "BR" }, "maxAds": { "type": "integer", "title": "Maximum Meta ads", "description": "Bounded SSR evidence limit. v1 caps this at 30 public ads per mapping.", "default": 30, "minimum": 1, "maximum": 30 }, "maxAttempts": { "type": "integer", "title": "SSR prefetch attempts", "description": "Retries when Meta returns the Ad Library shell without the prefetched results payload.", "default": 3, "minimum": 1, "maximum": 5 }, "requestTimeoutSeconds": { "type": "integer", "title": "Meta request timeout", "default": 20, "minimum": 5, "maximum": 60, "description": "Per-request timeout for the anonymous public Meta Ad Library source." } } } } }, "default": { "metaAdsLibrary": [] }, "additionalProperties": false }, "firstPartyValidation": { "title": "First-party validation", "type": "object", "description": "Optionally attach immutable customer-declared experiment results to stable opportunity IDs. AdPulse stores descriptive deltas but does not infer statistical significance, causal effect, winner status, or competitor performance.", "properties": { "enabled": { "title": "Enable first-party result ingestion", "type": "boolean", "default": false, "description": "When enabled, validated records are linked to current durable opp_* opportunity identities and persisted in the monitor ledger." }, "records": { "title": "First-party result records", "type": "array", "default": [], "maxItems": 100, "description": "Completed first-party test results. Outcomes are declared by the customer/system of record; AdPulse does not derive validated/rejected from the metric values.", "items": { "type": "object", "additionalProperties": false, "required": [ "validationId", "advertiserId", "opportunityId", "outcome", "metricName", "controlValue", "variantValue", "observedAt" ], "properties": { "validationId": { "title": "Immutable validation ID", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]{1,100}$", "description": "Stable non-PII identifier for this submitted result. The same ID may be replayed only with identical content." }, "advertiserId": { "title": "Advertiser ID", "type": "string", "description": "Must exactly match one advertiserIds target in this run." }, "opportunityId": { "title": "Opportunity ID", "type": "string", "pattern": "^opp_[0-9a-f]{20}$", "description": "Stable I5 opp_* ID shown in OPPORTUNITY_EVIDENCE / DASHBOARD_DATA." }, "outcome": { "title": "Declared outcome", "type": "string", "enum": [ "validated", "rejected", "inconclusive" ], "description": "Customer/system-declared result. AdPulse does not infer this classification from metric deltas." }, "metricName": { "title": "Primary metric", "type": "string", "minLength": 1, "maxLength": 80, "description": "Canonical first-party metric name, for example conversion_rate or qualified_lead_rate." }, "metricDirection": { "title": "Metric direction", "type": "string", "enum": [ "higher_is_better", "lower_is_better", "neutral" ], "default": "neutral", "description": "Descriptive direction metadata only; it does not create a winner or significance claim." }, "controlValue": { "title": "Control value", "type": "number", "description": "Aggregate first-party control value. Raw user-level data should not be supplied." }, "variantValue": { "title": "Variant value", "type": "number", "description": "Aggregate first-party variant value. AdPulse records the descriptive delta only." }, "controlSampleSize": { "title": "Control sample size", "type": "integer", "minimum": 1, "description": "Optional aggregate sample size. No significance test is inferred from it." }, "variantSampleSize": { "title": "Variant sample size", "type": "integer", "minimum": 1, "description": "Optional aggregate sample size. No significance test is inferred from it." }, "observedAt": { "title": "Result observed at", "type": "string", "description": "ISO-8601 timestamp with explicit timezone for the first-party result." }, "sourceSystem": { "title": "Source system", "type": "string", "minLength": 1, "maxLength": 64, "default": "manual", "description": "Short provenance label such as manual, ga4, internal-experiment, or warehouse-export. Do not put credentials here." } } } } }, "default": { "enabled": false, "records": [] }, "additionalProperties": 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 } } } } } } } } } }