📣 Facebook Ads Creative Monitor

Detect newly launched, persistent and rapidly iterated competitor ad creatives.

Built for performance marketers and agencies, this Actor turns current and historical advertiser or creative records into a ranked, evidence-backed action queue. Bring the records; get the changes, priorities, risks, and source evidence that deserve attention.

🚀 What this Actor helps you do

• Act on the workflow: Detect newly launched, persistent and rapidly iterated competitor ad creatives.
• Review exceptions, not raw feeds: rank new, changed, removed, or optionally unchanged entities by priority.
• Explain every result: keep reasons, exact changed fields, confidence, source provenance, and a SHA-256 evidence digest.
• Automate the handoff: send structured results to a dataset, API client, webhook, spreadsheet, BI tool, CRM, or alerting workflow.

This is a decision layer, not a hidden scraper. You choose the lawful data source and can reproduce every result by supplying explicit current and previous snapshots.

✨ Workflow advantages

• Creative Fingerprinting — Suppress repeated input entities and produce canonical records that are ready for downstream grouping.
• Launch And Longevity Tracking — Compare explicit current and previous snapshots to expose meaningful field-level movement.
• Landing Page Evidence — Preserve reasons, changed fields, source context, and a deterministic evidence digest.

Every run also applies deterministic entity matching, configurable field comparison, duplicate suppression, opportunity/risk term checks, and output limits.

🎯 Common use cases

1. Core workflow — Detect newly launched, persistent and rapidly iterated competitor ad creatives.
2. Scheduled monitoring — run on a cadence and compare the latest records with the prior snapshot.
3. Team action queue — route only high-priority results to performance marketers and agencies.
4. Evidence export — retain source records and field-level reasons for QA, reporting, or human review.

📥 Input options

For production, connect a customer-selected upstream Actor or dataset that returns the relevant public or authorized records.

Mode	When to use it
inline	Fast tests, API integrations, or records assembled in your own code
dataset	Production pipelines that already write current records to Apify
upstream-actor	Run one explicitly selected upstream Actor and analyze its dataset
official-api	Read an authorized HTTPS JSON endpoint with secret request headers

Add previousRecords or previousDatasetId to detect changes. Exact platform IDs are preferred; fuzzy matching is available when strong identifiers are missing.

Default identity fields: adArchiveId, adId, id, snapshotUrl, pageId, url

Default comparison fields: pageName, headline, body, ctaText, status, startDate, endDate, impressions, spend, reach, platforms

⚡ Quick start

Paste this into the Actor input editor and replace the sample records with your own:

{
  "sourceMode": "inline",
  "records": [
    {
      "adArchiveId": "ad-demo-001",
      "pageName": "Peak Coffee",
      "headline": "Cold brew subscription — 30% off",
      "body": "New summer bundle. Shop now.",
      "ctaText": "SHOP_NOW",
      "status": "ACTIVE",
      "impressions": 840000,
      "spend": 12800,
      "reach": 611000,
      "daysActive": 42,
      "creativeCount": 3,
      "observedAt": "2026-08-02T10:00:00Z",
      "productWorkflow": "facebook-ads-creative-monitor"
    }
  ],
  "previousRecords": [
    {
      "adArchiveId": "ad-demo-001",
      "pageName": "Peak Coffee",
      "headline": "Cold brew delivered",
      "body": "Subscribe today.",
      "ctaText": "SHOP_NOW",
      "status": "ACTIVE",
      "impressions": 510000,
      "spend": 8900,
      "reach": 432000,
      "daysActive": 28,
      "creativeCount": 2,
      "observedAt": "2026-07-19T10:00:00Z",
      "productWorkflow": "facebook-ads-creative-monitor"
    }
  ],
  "minimumScore": 35,
  "maxEvents": 100,
  "includeNew": true,
  "includeChanged": true,
  "includeRemoved": false
}

Then adjust:

• minimumScore to control how selective the action queue is.
• maxEvents to cap delivered insights.
• includeNew, includeChanged, includeRemoved, and includeUnchanged to define which states matter.
• customIdFields and customCompareFields when your source schema uses different names.

📤 Output you can use immediately

Each delivered dataset item includes:

Field	Meaning
eventType	new, changed, removed, or unchanged
entityId / entityLabel	Canonical machine ID and readable entity name
priorityScore	Deterministic 0–100 review priority
riskScore	Deterministic 0–100 caution signal
confidence	Evidence completeness and identity confidence from 0–1
reasons	Plain-language reasons behind the ranking
changedFields	Exact fields that changed from the previous snapshot
current / previous	Sanitized source evidence used for comparison
sourceType / sourceId	Non-secret provenance for the input records
evidenceDigest	SHA-256 digest of canonical current/previous evidence

The KVS OUTPUT record contains the run summary, counts, duplicate diagnostics, and score range.

🔌 API and automation

Run the Actor through the API:

curl -X POST \
  "https://api.apify.com/v2/acts/night111~facebook-ads-creative-monitor/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @input.json

Use the returned defaultDatasetId to fetch results. For unattended workflows, combine the Actor with Apify schedules, webhooks, API clients, Make, Zapier, or your own orchestration service.

🧠 How decisions are produced

The Actor uses explainable rules over configured identity fields, field deltas, numeric movement, opportunity terms, caution terms, completeness, and identity confidence. It does not present a model-generated verdict as fact. Important actions should be checked against the attached source evidence.

🛡️ Responsible use and scope

• Workflow-specific caution: Public Ads Library data; creative interpretation is non-authoritative.
• Process only data you are authorized to use and follow source-site terms, privacy rules, retention duties, and applicable outreach laws.
• Product and platform names belong to their respective owners. This independent Actor is not endorsed by those platforms.
• Secret API headers are encrypted by Apify, omitted from outputs, and credential-like evidence fields are stripped.
• Do not place tokens in dataset or API URLs; common credential patterns are rejected.

⚠️ Limitations

• Output quality depends on the completeness, freshness, legality, and schema consistency of your input records.
• Fuzzy entity resolution is best-effort; stable source IDs produce better comparisons.
• State is explicit rather than hidden: provide a previous snapshot for reproducible change detection.
• Authorized API mode reads JSON responses; it is not an arbitrary HTML browser.
• Upstream Actors and external APIs may have separate availability, permissions, or usage constraints.

❓ FAQ

Does this Actor collect the source data itself?

Not silently. It analyzes records you provide inline, through datasets, via one explicitly selected upstream Actor, or from an authorized HTTPS JSON API.

Can I run it on a schedule?

Yes. Save each run’s current records as the next run’s previous snapshot, then use an Apify schedule or your orchestrator.

Can I use my own field names?

Yes. Set customIdFields and customCompareFields to align the workflow with your schema.

How do I keep a run bounded?

Use minimumScore and maxEvents. The Actor stops delivering new events once the configured output limit is reached.

💬 Support

Open the Actor Issues tab with a sanitized input example, run ID, expected entity key, and observed behavior. Never post credentials or private source data.