Facebook Ads Library Scraper + AI Creative Analysis

Scrape public ads from Facebook Ads Library / Meta Ad Library, then optionally turn selected Facebook, Instagram, Messenger, Threads, and Audience Network creatives into structured AI-powered marketing intelligence.

Use raw mode to collect ads by keyword or exact Facebook Page ID. Turn on Creative Metadata when you want each image or short video analyzed for hooks, offers, CTAs, visual tone, OCR/on-screen text, timeline frames, and marketer review notes.

How this differs from a regular Facebook ads scraper

Most Meta or Facebook Ad Library scrapers stop at raw ad 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 to understand why a creative works:

• rawOnly: zero Creative Metadata event charges; best for broad ad 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 when you need 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 breaking the raw scraper output.
• Analyze ad creatives for hook type, offer, CTA clarity, visual tone, brand presence, product visibility, and narrative structure.
• Get video timeline-lite frame analysis for short videos.
• Export clean JSON/CSV for Sheets, BI dashboards, creative swipe files, and downstream AI workflows.

Two modes

Mode	Best for	Cost behavior
Raw scraping	Collecting Meta Ad Library ads, copy, media URLs, platforms, and CTA links	No Creative Metadata event charge
Creative Metadata	Competitor creative research, ad teardown, swipe files, marketer review, AI-ready datasets	Charged only for completed AI analyses

Raw scraping works without a Gemini API key. Creative Metadata requires the Actor's GEMINI_API_KEY secret to be configured.

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. Use the Store example as a low-cost AI teaser: mediaType: "image", maxResults: 3, and maxAnalyzedMediaPerRun: 1. It can show Creative Metadata while capping analysis breadth.
2. For zero Creative Metadata event charges, run raw mode with maxResults: 5-10 to validate the keyword or exact Page ID first.
3. After selecting the strongest creatives, enable Creative Metadata or use analyzeDataset to enrich only those rows.
4. Keep maxAnalyzedMediaPerRun and analysisBudgetUsd low while testing a new niche or country.

Example input

Low-cost AI teaser used by the Store example:

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

Raw scraping only, with no Creative Metadata event charges:

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

Creative Metadata enabled for a selected small batch:

{
    "keywords": ["Nike"],
    "country": "US",
    "mediaType": "all",
    "pipelineMode": "crawlAndAnalyze",
    "maxResults": 10,
    "includeCreativeMetadata": true,
    "metadataTier": "image_basic_or_video_timeline_lite",
    "maxAnalyzedMediaPerRun": 5,
    "maxFramesPerVideo": 6,
    "maxVideoDurationSec": 60,
    "analysisBudgetUsd": 1.0,
    "saveRawFrames": false,
    "saveRawMedia": false,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

Creative Metadata controls

Default settings are conservative:

{
    "includeCreativeMetadata": false,
    "metadataTier": "image_basic_or_video_timeline_lite",
    "maxAnalyzedMediaPerRun": 20,
    "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.

Example creativeMetadata shape

The shortened example below is based on a verified static-image QA sample from run sOVBbfkoEFnqYt06i (buildNumber: 0.2.37, buildId: LapGcoMPAFKgzsVJT). It analyzed one raw row from source dataset ql6ElCzNPL7fauVkp / source run UWNN5E6PhYUf2b24d and wrote one enriched row to dataset Mg7MkiqLwtNBxe5kV with KVS fFvdoNedCkS9K1LXF. The row was returned for keyword Nike with brand field Nicholas Ralph; treat it as a third-party ad match, not an advertiser-owned Nike example. URL/media fields are omitted from this README excerpt, but every field shown below is copied from that run's dataset item or COST_SUMMARY.

{
    "libraryID": "1388117083374637",
    "keyword": "Nike",
    "brand": "Nicholas Ralph",
    "body": "A fresh take on the Nike Mind 001. New colorways, same standout look. Shop the latest pairs now.",
    "startDate": "2026-06-16",
    "isActive": true,
    "platforms": ["Facebook", "Instagram", "Audience Network", "Messenger", "Threads"],
    "source": {
        "type": "dataset",
        "sourceDatasetId": "ql6ElCzNPL7fauVkp",
        "sourceRunId": "UWNN5E6PhYUf2b24d",
        "sourceItemIndex": 0,
        "dedupeKeySource": "creativeFingerprint"
    },
    "creativeMetadata": {
        "status": "completed",
        "mediaType": "image",
        "languagePolicy": "english_only",
        "tier": "image_basic",
        "provider": "gemini",
        "model": "gemini-2.5-flash-lite",
        "analysisCoverage": "static_image",
        "frameCount": 1,
        "samplingPolicy": "static_image",
        "failureCode": "",
        "T1": {
            "hookType": "sale",
            "messageCore": "Factory direct sale up to 70% off limited time only.",
            "format": "image",
            "visualTone": "promotional",
            "talentType": "none",
            "endingCta": "Shop now, limited stock, act fast!",
            "durationSec": 0,
            "targetTone": "urgent",
            "subtitleKeywords": []
        },
        "T2": {
            "transcriptEnglish": "unknown",
            "onScreenTextEnglish": "FACTORY DIRECT SALE UP TO 70% OFF LIMITED TIME ONLY! NO MIDDLEMAN BETTER PRICE PREMIUM RECOVERY SLIDES LIGHTWEIGHT FEELS LIKE WALKING ON CLOUDS BREATHABLE KEEP YOUR FEET COOL & DRY ALL-DAY COMFORT SUPPORTS EVERY STEP YOU TAKE FREE SHIPPING ON ALL ORDERS 30-DAY RISK FREE RETURN POLICY SHOP NOW LIMITED STOCK - ACT FAST!",
            "narrativeStructure": "informational",
            "claims": ["Up to 70% off", "Limited time only", "No middleman, better price", "Lightweight", "Breathable"],
            "offer": "Up to 70% off sale on premium recovery slides.",
            "painPoint": "unknown"
        },
        "T3": {
            "visualComposition": "product-focused",
            "productVisibility": "high",
            "brandPresence": "low",
            "ctaClarity": "high",
            "persuasionAngle": "discount-driven",
            "complianceSignals": ["Free shipping", "Risk-free return policy"]
        },
        "timeline": [
            {
                "time": "image",
                "timestampSec": 0,
                "frameIndex": 0,
                "description": "The image displays a sale advertisement for premium recovery slides. Key text includes \"FACTORY DIRECT SALE\", \"UP TO 70% OFF\", and \"LIMITED TIME ONLY!\". The slides are shown prominently with features like \"LIGHTWEIGHT\", \"BREATHABLE\", and \"ALL-DAY COMFORT\" listed. \"FREE SHIPPING ON ALL ORDERS\" and \"30-DAY RISK FREE RETURN POLICY\" are also visible. The call to action is \"SHOP NOW LIMITED STOCK - ACT FAST!\".",
                "visibleTextEnglish": [
                    "FACTORY DIRECT",
                    "SALE",
                    "UP TO",
                    "70%",
                    "OFF",
                    "LIMITED TIME ONLY!",
                    "NO MIDDLEMAN",
                    "BETTER PRICE",
                    "PREMIUM RECOVERY SLIDES",
                    "LIGHTWEIGHT",
                    "FEELS LIKE WALKING ON CLOUDS",
                    "BREATHABLE",
                    "KEEP YOUR FEET COOL & DRY",
                    "ALL-DAY COMFORT",
                    "SUPPORTS EVERY STEP YOU TAKE",
                    "FREE SHIPPING",
                    "ON ALL ORDERS",
                    "30-DAY RISK FREE",
                    "RETURN POLICY",
                    "SHOP NOW"
                ],
                "objects": ["slides", "text", "icon"],
                "sceneType": "static_image"
            }
        ],
        "creativeReview": {
            "summary": "This is a visually striking image ad for a sale on recovery slides. It effectively uses bold text and clear calls to action to convey a sense of urgency and value. The product features are well-articulated, and trust signals like free shipping and a risk-free return policy are present.",
            "strengths": [
                "Clear and prominent sale messaging",
                "Strong call to action",
                "Highlights key product benefits",
                "Includes trust signals (free shipping, return policy)"
            ],
            "weaknesses": [
                "No visible brand logo for the slides themselves",
                "Limited context on the specific brand of slides"
            ],
            "marketerNotes": [
                "Consider adding the brand logo if available.",
                "Test different discount percentages or sale durations."
            ],
            "recommendedTests": [
                "A/B test different headlines emphasizing discount vs. product benefits.",
                "Test variations of the CTA button text.",
                "Experiment with different background imagery or product angles."
            ]
        },
        "lowConfidenceFields": [],
        "technical": {
            "mimeType": "image/jpeg",
            "frameCount": 1,
            "sampleTimestampsSec": [0],
            "rawMediaSaved": false,
            "rawFramesSaved": false,
            "providerLatencyMs": 4852,
            "providerEstimatedCostUsd": 0.0028383
        },
        "charge": {
            "eligible": true,
            "applied": true,
            "eventName": "creative_image_basic",
            "chargedCount": 1,
            "eventChargeLimitReached": false
        }
    }
}

Grounded static-image evidence from the same output:

Field	Value from verified image sample
Run / build	sOVBbfkoEFnqYt06i / 0.2.37 / LapGcoMPAFKgzsVJT
Dataset / item count	Mg7MkiqLwtNBxe5kV / 1
KVS evidence	fFvdoNedCkS9K1LXF with COST_SUMMARY
Creative status	completed
Media type / tier	image / image_basic
Timeline evidence	time: "image", timestampSec: 0, frameIndex: 0
Visible text sample	FACTORY DIRECT, SALE, UP TO, 70%, OFF, LIMITED TIME ONLY!, NO MIDDLEMAN, BETTER PRICE, PREMIUM RECOVERY SLIDES, LIGHTWEIGHT, ...
Charge object	eventName: creative_image_basic, chargedCount: 1, applied: true
Run charged events	creative_image_basic: 1, creative_video_timeline_lite: 0
Raw artifact flags	rawMediaSaved: false, rawFramesSaved: false

COST_SUMMARY excerpt from the same KVS:

{
    "key": "COST_SUMMARY",
    "providerCallCount": 1,
    "estimatedProviderCostUsd": 0.0028383,
    "eventPriceUsd": {
        "creative_image_basic": 0.05
    },
    "netRevenueAfterApifyUsd": {
        "creative_image_basic": 0.04
    },
    "providerCostUsd": 0.0028383,
    "grossMarginAfterProviderUsd": 0.0371617,
    "providerCostToNetRevenueRatio": 0.0709575,
    "chargeAttemptCount": 1,
    "chargeSuccessCount": 1,
    "chargeFailureCount": 0,
    "statusCounters": {
        "not_requested": 0,
        "skipped": 0,
        "failed_pre_provider": 0,
        "failed_provider": 0,
        "completed": 1,
        "completed_partial": 0,
        "charge_failed": 0
    },
    "chargedEventCounts": {
        "creative_image_basic": 1
    }
}

Gemini API key setup

Creative Metadata requires a Gemini API key. Raw scraping does not.

The Actor reads the key only from the GEMINI_API_KEY environment variable or Apify Secret configured in Apify Console. 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.

How to set or change the key in Apify Console

1. Open Apify Console.
2. Go to this Actor.
3. Open Settings or Environment variables / Secrets.
4. Add or update the secret used by GEMINI_API_KEY (current alias: metaAdCreativeIntelligenceGeminiApiKey).
5. Save the change.
6. Start a new run 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.