Meta/Facebook Ads Library Scraper + AI Creative Intelligence

Scrape Facebook Ads Library / Meta Ad Library ads by keyword or exact Facebook Page ID, then turn only the creatives you choose into AI creative intelligence. If you searched for a Facebook Ads Library scraper, Meta Ad Library scraper, Facebook ads scraper, or Meta ads scraper but need more than a raw export, use this Actor to add hooks, offers, CTAs, OCR/on-screen text, visual tone, timeline-lite evidence, and marketer review notes.

Start with broad raw scraping, filter the rows that matter, and enrich a capped number of image or video creatives. The raw path stays available for broad collection; paid Creative Metadata runs only when you enable it and a selected image/video analysis completes successfully.

Recommended workflow: scrape broadly, enrich selectively

1. Collect broadly with rawOnly — gather Meta/Facebook ad rows, media URLs, copy, dates, CTA links, and platforms with zero Creative Metadata event charges.
2. Pick the strongest rows — filter by brand, Page ID, media type, country, date, or your own review process.
3. Enrich selected creatives — use crawlAndAnalyze for a small live batch or analyzeDataset when you already have a raw dataset to enrich.
4. Control spend while testing — cap paid analysis with maxAnalyzedMediaPerRun and analysisBudgetUsd; rows that are skipped, provider-failed, budget-capped, or missing media are not charged for Creative Metadata.

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: 3, 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.

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.

Verified output preview from current runtime evidence

The shortened examples below are copied from verified build 0.2.44 runs used for this copy-only experiment. This README/Store update does not change runtime code, input schema, output schema, PPE events, or pricing. URL/media fields are omitted from the README excerpt, but every field shown below was present in the run output or cost evidence.

Image sample source: run eBs2QmZkVCyUOx2z1, dataset kqmdHNEptvOpxtG4j, build 0.2.44 / hvAQ8DiahG4L0TnN8, chargedEventCounts.creative_image_basic: 1, chargeFailureCount: 0.

{
    "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,
        "T1": {
            "hookType": "product_showcase",
            "messageCore": "New Nike Free Metcon 7 colors available.",
            "format": "image",
            "visualTone": "clean",
            "endingCta": "shop_now"
        },
        "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.",
                "objects": ["shoe", "laces"],
                "sceneType": "static_image"
            }
        ],
        "creativeReview": {
            "summary": "This is a clean and direct image ad showcasing a new Nike shoe.",
            "strengths": ["Clear product focus", "Vibrant background", "Prominent branding"],
            "weaknesses": ["Lack of context for use", "No explicit call to action text on the image"],
            "recommendedTests": ["Test different background colors", "Test with lifestyle imagery"]
        },
        "technical": {
            "rawMediaSaved": false,
            "rawFramesSaved": false,
            "providerEstimatedCostUsd": 0.0016709
        },
        "charge": {
            "eligible": true,
            "applied": true,
            "eventName": "creative_image_basic",
            "chargedCount": 1
        }
    }
}

Video sample source: run V4bN9zZD8QnClgrbd, dataset 4qXrpeCP3SRhXfTCm, build 0.2.44 / hvAQ8DiahG4L0TnN8, chargedEventCounts.creative_video_timeline_lite: 1, chargeFailureCount: 0.

{
    "libraryID": "973096598386271",
    "keyword": "Temu",
    "brand": "Novellist1",
    "startDate": "2026-04-04",
    "isActive": false,
    "platforms": ["Facebook", "Instagram"],
    "creativeMetadata": {
        "status": "completed",
        "mediaType": "video",
        "tier": "video_timeline_lite",
        "provider": "gemini",
        "model": "gemini-2.5-flash-lite",
        "analysisCoverage": "full_media",
        "durationSec": 37,
        "analyzedDurationSec": 37,
        "frameCount": 3,
        "samplingPolicy": "duration_aware_uniform_sampling",
        "T1": {
            "hookType": "intrigue",
            "messageCore": "A man is holding a baby, but the text suggests a story of betrayal and revenge.",
            "format": "video",
            "visualTone": "dramatic"
        },
        "sampleTimestampsSec": [0, 18.45, 36.9],
        "timeline": [
            {
                "time": "0s",
                "timestampSec": 0,
                "frameIndex": 0,
                "description": "A man in a suit holds a baby. On-screen text appears.",
                "visibleTextEnglish": ["Before the wedding, my fiance kissed his lover shamelessly in front of me."]
            },
            {
                "time": "18.45s",
                "timestampSec": 18.45,
                "frameIndex": 1,
                "description": "The man continues to hold the baby. More on-screen text is displayed."
            },
            {
                "time": "36.90s",
                "timestampSec": 36.9,
                "frameIndex": 2,
                "description": "The man looks down at the baby. The final on-screen text appears."
            }
        ],
        "creativeReview": {
            "summary": "The video uses a dramatic narrative about betrayal and revenge in a marriage.",
            "strengths": ["Intriguing narrative hook", "Dramatic tone", "Visual contrast between imagery and text"],
            "weaknesses": ["No clear product or service advertised", "CTA is missing"]
        },
        "technical": {
            "rawMediaSaved": false,
            "rawFramesSaved": false,
            "providerEstimatedCostUsd": 0.007218
        },
        "charge": {
            "eligible": true,
            "applied": true,
            "eventName": "creative_video_timeline_lite",
            "chargedCount": 1
        }
    }
}

COST_SUMMARY evidence across the two verified runs showed chargeFailureCount: 0, no unknown PPE event warnings, no provider errors, and no signed media URLs or API keys in logs.

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.