AI Creative Teardown for Meta/Facebook Ads

Scrape → Select → AI teardown

1. Scrape: collect raw Meta/Facebook Ad Library rows for advertiser, copy, dates, CTA links, platforms, and media URLs.
2. Select: select the creatives you want to review, either from a fresh crawl or an existing raw dataset.
3. AI teardown: add structured Creative Metadata that can return hooks, offers, CTAs, OCR/on-screen text, visual style, weaknesses, and review hypotheses.

Each successfully completed image analysis emits one creative_image_basic Creative Metadata event priced at $0.05. Video timeline-lite is also available at $0.20 for each successfully completed video timeline-lite analysis. Apify platform usage, Residential proxy usage, and applicable taxes may still apply separately according to your Apify plan and billing location.

Built for: agencies auditing competitors, DTC and e-commerce marketers building swipe files, and researchers comparing creative patterns.

What the teardown helps you review

• Hook and core message: group creatives by the opening angle and message they lead with.
• Offer and CTA: compare what is being offered, what action is requested, and whether the request is visually clear.
• OCR/on-screen text: make visible creative copy easier to search, filter, and export when the text can be read.
• Visual style: compare composition, product visibility, brand presence, tone, and sampled video scenes.
• Weaknesses and test ideas: turn observed gaps into hypotheses for human review; test ideas are not performance predictions.

Raw collection remains available without a Creative Metadata event charge when rawOnly or includeCreativeMetadata:false is selected explicitly. By default, a run enters the paid crawlAndAnalyze path so the Actor produces useful enriched output and eligible completed rows can generate Creative Metadata events.

Workflow	What you receive	Creative Metadata event price
Raw collection	Advertiser, copy, dates, CTA links, platforms, and media URLs	None
Image basic teardown	Structured static-image review	$0.05 for each completed image analysis
Video timeline-lite teardown	Bounded keyframe/timeline review	$0.20 for each completed video timeline-lite analysis

These are Creative Metadata event prices. Apify platform usage, Residential proxy usage, and applicable taxes may still apply according to your Apify plan and billing location. Skipped, failed, budget-capped, no-media, and media-type-mismatch rows have no Creative Metadata event charge.

First run: analyze at most 1 image

1. Start with one keyword or exact Facebook Page ID and keep maxResults: 2.
2. Use mediaType: "image" and maxAnalyzedMediaPerRun: 1, so only one matching returned image can become a paid teardown.
3. Review creativeMetadata: a completed image row uses the $0.05 creative_image_basic event; skipped or failed rows have no Creative Metadata event charge.

{
    "keywords": ["Nike"],
    "country": "US",
    "mediaType": "image",
    "pipelineMode": "crawlAndAnalyze",
    "maxResults": 2,
    "includeCreativeMetadata": true,
    "metadataTier": "image_basic_or_video_timeline_lite",
    "creativeAnalysisDepth": "basic",
    "maxAnalyzedMediaPerRun": 1,
    "maxFramesPerVideo": 6,
    "maxVideoDurationSec": 60,
    "analysisBudgetUsd": 0.25,
    "saveRawFrames": false,
    "saveRawMedia": false,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

First run: analyze at most 1 video timeline

Use mediaType: "video", a short analysis window, and a low frame cap. A successful video timeline-lite result uses the $0.20 creative_video_timeline_lite event.

{
    "keywords": ["Temu"],
    "country": "US",
    "mediaType": "video",
    "pipelineMode": "crawlAndAnalyze",
    "maxResults": 3,
    "includeCreativeMetadata": true,
    "metadataTier": "image_basic_or_video_timeline_lite",
    "creativeAnalysisDepth": "basic",
    "maxAnalyzedMediaPerRun": 1,
    "maxFramesPerVideo": 3,
    "maxVideoDurationSec": 60,
    "videoSamplingStrategy": "firstWindow",
    "analysisBudgetUsd": 0.5,
    "saveRawFrames": false,
    "saveRawMedia": false,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

analysisBudgetUsd is an estimated AI provider-cost safety limit, not the PPE event price and not a cap on Apify platform or proxy usage. When the projected next provider cost would exceed the cap, the Actor returns that row as failed_pre_provider with failureCode: "budget_cap" before media fetch/provider call and without a Creative Metadata charge attempt or application (chargedCount: 0).

Verified image output example

This secret-free excerpt comes from a completed image analysis. Media URLs and ad identifiers are omitted.

{
    "creativeMetadata": {
        "status": "completed",
        "mediaType": "image",
        "analysisCoverage": "static_image",
        "T1": {
            "hookType": "product_showcase",
            "messageCore": "New Nike Free Metcon 7 colors available.",
            "endingCta": "shop_now"
        },
        "T2": {
            "onScreenTextEnglish": "Nike",
            "offer": "new colors"
        },
        "T3": {
            "visualComposition": "product_centered",
            "productVisibility": "high",
            "brandPresence": "prominent",
            "ctaClarity": "high"
        },
        "creativeReview": {
            "strengths": ["Clear product focus", "Visually appealing color contrast", "Direct call to action"],
            "weaknesses": ["Lack of dynamic elements", "Limited information beyond product and newness"],
            "recommendedTests": [
                "Test different CTA button text.",
                "Test variations with different colorways of the shoe."
            ]
        },
        "charge": {
            "eventName": "creative_image_basic",
            "applied": true,
            "chargedCount": 1
        }
    }
}

How this differs from a regular Facebook ads scraper

Most Meta or Facebook Ad Library scrapers stop at raw rows: advertiser, copy, dates, CTA links, platforms, and media URLs. This Actor keeps that raw export path, then adds an optional paid Creative Metadata layer for marketers who need structured creative teardown:

• rawOnly: zero Creative Metadata event charges; suited for broad Facebook Ads Library collection.
• crawlAndAnalyze: collect fresh ads and analyze a capped number of image/video creatives in one run.
• analyzeDataset: enrich an existing raw dataset after you have already selected the creatives worth analyzing.

Use it for competitive ad research, hook/offer/CTA teardown, OCR/on-screen text extraction, video timeline-lite evidence, and BI/Sheets-friendly creative labels — not just another raw export.

Why use this Actor?

• Find competitor ads by brand, keyword, product, exact Facebook Page ID, or Facebook Ads Library search term.
• Export raw Meta Ad Library data: copy, CTA links, media URLs, start dates, active status, and platforms.
• Add AI creative metadata only when needed, without changing the raw scraper output path.
• Analyze ad creatives for hook type, offer, CTA clarity, visual tone, brand presence, product visibility, and narrative structure.
• Get static-image evidence and video timeline-lite frame analysis for selected creatives.
• Export clean JSON/CSV for Sheets, BI dashboards, creative swipe files, and downstream AI workflows.

Two cost-safe paths

Path	Use when	Cost behavior
Raw scraping	Broad Facebook/Meta Ad Library collection: copy, media URLs, platforms, and CTA links	No Creative Metadata event charge
Selective AI enrichment	Competitor creative teardown, swipe files, marketer review, AI-ready datasets	Charged only after a successful AI analysis completes

Public Store users do not paste API keys into the input. Raw scraping makes zero provider calls. Creative Metadata uses the Actor's configured GEMINI_API_KEY environment secret and the per-run caps you set.

What this Actor returns

Base ad fields:

• libraryID
• keyword
• pageId
• brand
• brandImg
• body
• startDate
• isActive
• platforms
• images
• videos
• ctaLink
• scrapeDate

Optional premium field:

• creativeMetadata

creativeMetadata includes:

• English-only creative labels grouped into T1, T2, and T3.
• Static image context or video timeline-lite keyframe context.
• Hook, offer, CTA, pain point, persuasion angle, and visual tone.
• OCR/on-screen text translated or normalized to English when visible.
• Marketer review notes: strengths, weaknesses, and recommended tests.
• Capped label suggestions for human review.
• Low-confidence fields, provider usage, and charge metadata.

Pricing in plain English

Creative Metadata uses pay-per-event pricing and is charged only after an AI analysis completes successfully as completed or completed_partial.

Event	Charged when	Current launch price
creative_image_basic	One image creative metadata row completes successfully	$0.05
creative_video_timeline_lite	One video timeline-lite metadata row completes successfully	$0.20

Important pricing rules:

• Raw scraping with includeCreativeMetadata=false triggers no Creative Metadata event charges.
• completed and completed_partial metadata rows are charged only after schema-normalized AI output is available.
• skipped, failed_pre_provider, failed_provider, charge_failed, no-media, expired media URL, media fetch failure, provider failure, and budget-capped rows are not charged for Creative Metadata.
• mediaType=meme uses Meta Ad Library's meme filter. If Meta returns a row without extractable image or video media, Creative Metadata is skipped with failureCode: "no_media" and charge 0.
• Apify platform usage, residential proxy usage, and applicable taxes/VAT may apply according to the user's Apify plan, billing location, and platform billing rules.
• The Actor includes safety caps so users can control provider cost and analysis volume.

Recommended first run:

1. Run raw mode first with maxResults: 5-10 to validate the keyword or exact Page ID with zero Creative Metadata event charges.
2. Use the Store example as a low-cost AI teaser: mediaType: "image", maxResults: 2, maxAnalyzedMediaPerRun: 1, and analysisBudgetUsd: 0.25.
3. For a selected batch, keep maxAnalyzedMediaPerRun and analysisBudgetUsd low while testing a new niche or country.
4. For repeat workflows, scrape broad raw datasets first, then use analyzeDataset to enrich only the creatives you want to review.

First-run budget-capped examples

Use these small examples to test the workflow before scaling up. maxAnalyzedMediaPerRun limits how many creatives can become paid Creative Metadata rows, while analysisBudgetUsd caps estimated AI provider spend before the next provider call.

Raw scraping only, with no Creative Metadata event charges:

{
    "keywords": ["Nike"],
    "country": "US",
    "pipelineMode": "rawOnly",
    "maxResults": 10,
    "includeCreativeMetadata": false,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

Cost-capped image creative teardown:

{
    "keywords": ["Nike"],
    "country": "US",
    "mediaType": "image",
    "pipelineMode": "crawlAndAnalyze",
    "maxResults": 2,
    "includeCreativeMetadata": true,
    "metadataTier": "image_basic_or_video_timeline_lite",
    "creativeAnalysisDepth": "basic",
    "maxAnalyzedMediaPerRun": 1,
    "maxFramesPerVideo": 6,
    "maxVideoDurationSec": 60,
    "analysisBudgetUsd": 0.25,
    "saveRawFrames": false,
    "saveRawMedia": false,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

Cost-capped video timeline-lite teardown:

{
    "keywords": ["Temu"],
    "country": "US",
    "mediaType": "video",
    "pipelineMode": "crawlAndAnalyze",
    "maxResults": 3,
    "includeCreativeMetadata": true,
    "metadataTier": "image_basic_or_video_timeline_lite",
    "creativeAnalysisDepth": "basic",
    "maxAnalyzedMediaPerRun": 1,
    "maxFramesPerVideo": 3,
    "maxVideoDurationSec": 60,
    "videoSamplingStrategy": "firstWindow",
    "analysisBudgetUsd": 0.5,
    "saveRawFrames": false,
    "saveRawMedia": false,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

For repeat workflows, scrape broad raw datasets first, then use analyzeDataset to enrich only the creatives you want to review.

Prevent and troubleshoot media type mismatch

mediaType controls both Meta collection filtering and which returned media the Creative Metadata step may analyze. Meta can still return a row whose extractable media does not match the request, so check creativeMetadata.mediaType and creativeMetadata.failureCode rather than assuming every returned row is analyzable.

• image: analyzes image rows. A video-only row is skipped as media_type_mismatch; it does not consume the image analysis cap or fall back to video analysis.
• video: analyzes video rows. An image-only row is skipped as media_type_mismatch before media fetch, provider, or billing work.
• meme: uses Meta's meme filter but the analysis path selects images only. A video-only result is not analyzed from its poster frame; it is skipped as media_type_mismatch. A row with no extractable media is no_media.
• all: accepts either type and preserves video-before-image selection when a row contains both. Use this when either event price is acceptable for the run.
• none: performs no AI analysis. Rows with media are skipped as media_type_mismatch; there are zero provider calls and zero Creative Metadata charge attempts.

For media_type_mismatch, the row is expected to show charge.eligible: false, charge.applied: false, and chargedCount: 0, with no provider call or Creative Metadata charge attempt. To obtain a teardown, rerun with the matching mediaType, use all when either media type is acceptable, or select a source dataset containing the requested media.

Creative Metadata controls

The default run is the paid Creative Metadata path. Use pipelineMode:"rawOnly" (or includeCreativeMetadata:false when pipelineMode is omitted) for an explicitly free raw scrape.

Default settings are:

{
    "pipelineMode": "crawlAndAnalyze",
    "includeCreativeMetadata": true,
    "metadataTier": "image_basic_or_video_timeline_lite",
    "maxAnalyzedMediaPerRun": 50,
    "maxFramesPerVideo": 6,
    "maxVideoDurationSec": 60,
    "maxVideoBytes": 100000000,
    "analysisBudgetUsd": 3.0,
    "saveRawFrames": false,
    "saveRawMedia": false,
    "debugSavePageScreenshot": false
}

Important rules:

• Before a provider call, the Actor checks that the matching PPE event is configured and still chargeable within the run budget. If not, the row is skipped before Gemini is called.
• COST_SUMMARY records pricing-safety evidence including event price, realized net revenue after Apify margin from successful charges, provider cost, gross margin after provider, and provider-cost/net-revenue ratios.
• If Gemini returns HTTP 200 but malformed or empty JSON after consuming provider tokens, the row is marked as failed_provider with failureCode: "gemini_malformed_json" and Creative Metadata charge 0. Provider-cost evidence remains visible in COST_SUMMARY so failures are auditable without billing the user for unusable metadata.
• Completed metadata charges are retried on transient Apify charge API errors before the row is marked as uncharged, reducing provider-cost leakage from temporary billing API failures.
• Static image rows that complete metadata analysis always include exactly one image timeline item with time: "image" and timestampSec: 0.
• labelSuggestions is capped to 5 items and is review-only. The Actor never auto-adds suggestions to a vocabulary.
• Videos longer than maxVideoDurationSec use timeline-lite first-N-second sampling and emit completed_partial when metadata completes; failed media/tooling/provider/budget paths remain charge 0.
• No raw video, frame files, or page screenshots are saved by default.
• PAGE_SCREENSHOT is written to the key-value store only when debugSavePageScreenshot is explicitly set to true.
• Output is normalized to English/ASCII-safe text to improve CSV, Sheets, and BI compatibility.
• Media URLs, raw frame paths, page screenshot data, and API keys are not logged.

Additional verified image and video output examples

The shortened examples below come from completed paid analyses. URL/media fields plus internal run, build, Dataset, and KVS identifiers are omitted; the displayed output fields were present in the analysis results.

This image example completed with creative_image_basic applied once and no charge failure.

{
    "libraryID": "1670677960896587",
    "keyword": "Nike",
    "brand": "Box Basics",
    "startDate": "2026-07-07",
    "isActive": true,
    "platforms": ["Facebook", "Instagram", "Audience Network", "Messenger", "Threads"],
    "creativeMetadata": {
        "status": "completed",
        "mediaType": "image",
        "tier": "image_basic",
        "provider": "gemini",
        "model": "gemini-2.5-flash-lite",
        "analysisCoverage": "static_image",
        "frameCount": 1,
        "samplingPolicy": "static_image",
        "T1": {
            "hookType": "product_showcase",
            "messageCore": "New Nike Free Metcon 7 colors available.",
            "format": "image",
            "visualTone": "clean",
            "talentType": "none",
            "endingCta": "shop_now",
            "durationSec": 0,
            "targetTone": "exciting",
            "subtitleKeywords": []
        },
        "sampleTimestampsSec": [0],
        "timeline": [
            {
                "time": "image",
                "timestampSec": 0,
                "frameIndex": 0,
                "description": "A black Nike Free Metcon 7 shoe with a white sole is displayed against a yellow background. The laces are loosely tied and draped.",
                "visibleTextEnglish": ["unknown"],
                "objects": ["shoe", "laces"],
                "sceneType": "static_image"
            }
        ],
        "creativeReview": {
            "summary": "This is a static image ad featuring a single Nike Free Metcon 7 shoe on a yellow background. The ad highlights new color drops and encourages immediate purchase.",
            "strengths": [
                "Clear product focus",
                "Vibrant background color",
                "Direct call to action implied by body text"
            ],
            "weaknesses": [
                "Static image lacks dynamic appeal",
                "No explicit CTA button visible in the image",
                "Limited information about the product's features"
            ],
            "recommendedTests": [
                "A/B test with a video showcasing the shoe in action.",
                "Test different headlines emphasizing the 'new drop' aspect.",
                "Test variations with different angles or multiple shoes."
            ]
        },
        "technical": {
            "rawMediaSaved": false,
            "rawFramesSaved": false,
            "providerEstimatedCostUsd": 0.0017284,
            "sampleTimestampsSec": [0]
        },
        "charge": {
            "eligible": true,
            "applied": true,
            "eventName": "creative_image_basic",
            "chargedCount": 1
        }
    }
}

This video example completed with creative_video_timeline_lite applied once and no charge failure.

{
    "libraryID": "4461152980824511",
    "keyword": "Nike",
    "brand": "Statique",
    "startDate": "2026-07-08",
    "isActive": true,
    "platforms": ["Facebook", "Instagram", "Audience Network", "Messenger", "Threads"],
    "creativeMetadata": {
        "status": "completed_partial",
        "mediaType": "video",
        "tier": "video_timeline_lite",
        "provider": "gemini",
        "model": "gemini-2.5-flash-lite",
        "analysisCoverage": "first_60_seconds_scene_sampled",
        "durationSec": 209.366667,
        "analyzedDurationSec": 60,
        "frameCount": 1,
        "samplingPolicy": "first_n_seconds_plus_scene_keyframe_sampling",
        "T1": {
            "hookType": "question",
            "messageCore": "Many families lose time, money, and property due to lack of estate planning.",
            "format": "explainer",
            "visualTone": "informative",
            "talentType": "unknown",
            "endingCta": "Get your guide",
            "durationSec": 209.37,
            "targetTone": "informative",
            "subtitleKeywords": ["estate planning", "probate", "assets", "loved ones", "guide"]
        },
        "sampleTimestampsSec": [0],
        "timeline": [
            {
                "time": "0s",
                "timestampSec": 0,
                "frameIndex": 0,
                "description": "A man is working on what appears to be a fiber optic light installation, with text overlay \"LIGHTS IN THE ROOF !\".",
                "visibleTextEnglish": ["LIGHTS IN THE ROOF !"],
                "objects": ["man", "glasses", "fiber optics", "window"],
                "sceneType": "demonstration"
            }
        ],
        "creativeReview": {
            "summary": "The video uses a relatable pain point about estate planning to introduce a guide. The on-screen text in the sampled frame is unrelated to the ad's core message, which could be confusing. The duration is long for a typical ad, suggesting it might be a longer-form explainer or repurposed content.",
            "strengths": [
                "Addresses a common and important life event (estate planning).",
                "Clearly states the problem and offers a solution (the guide)."
            ],
            "weaknesses": [
                "The on-screen text in the sampled frame is irrelevant to the ad's message.",
                "The video duration is very long.",
                "The visual content in the sampled frame does not directly illustrate the topic of estate planning."
            ],
            "recommendedTests": [
                "Test different on-screen text overlays that are more relevant to estate planning.",
                "Test shorter versions of the video.",
                "Test visuals that more directly represent estate planning concepts."
            ]
        },
        "technical": {
            "rawMediaSaved": false,
            "rawFramesSaved": false,
            "providerEstimatedCostUsd": 0.0026998,
            "durationSec": 209.366667,
            "analyzedDurationSec": 60,
            "samplingPolicy": "first_n_seconds_plus_scene_keyframe_sampling",
            "sampleTimestampsSec": [0]
        },
        "charge": {
            "eligible": true,
            "applied": true,
            "eventName": "creative_video_timeline_lite",
            "chargedCount": 1
        }
    }
}

Both examples completed without charge failures. Skipped and failed analyses remain non-billable as described above.

Gemini API key and billing safety

Raw scraping does not require a Gemini API key and makes zero provider calls. Public Store users do not paste API keys into Actor input.

Creative Metadata uses the Actor's configured GEMINI_API_KEY environment variable or Apify Secret. The source bundle references a product secret alias only; it does not contain a key value. The key is never printed to logs, dataset rows, key-value store records, or README examples.

Operator note: if you maintain a private fork or staging copy, configure the GEMINI_API_KEY secret in Apify Console before running Creative Metadata. Start a new run after changing the secret so the new environment value is used.

If includeCreativeMetadata is false, the Actor makes zero provider calls even when no key is configured.

If includeCreativeMetadata is true and the key is missing or invalid, affected rows fail at the metadata level with a clear creativeMetadata.status and failureCode. The key value is never exposed.

Operational notes

• Use Apify Residential proxy for reliable Meta Ad Library pagination.
• Start with small maxResults and maxAnalyzedMediaPerRun values while validating a new keyword or brand.
• Provider cost is controlled by analysisBudgetUsd, media count caps, video duration caps, and frame caps.
• This Actor is not affiliated with, endorsed by, or sponsored by Meta, Facebook, or Instagram.
• This Actor does not provide legal or policy compliance decisions. Use the output as creative intelligence for human review.