meta-ads-library

Meta Ads Library

Guide for searching the Meta Ads Library and producing structured competitor ad intelligence.

The skill's job is to turn raw scraped ads into useful summaries: top advertisers, common CTAs, recurring hooks, recently launched creatives, and (optionally) enriched lead lists. All output is presented inline in chat — there is no database or persistence layer.

Out of scope — defer to other skills

| Request | Send them to | | --- | --- | | Multi-source competitor research (site, social, search rank, etc., not just ads) | [competitor-intel](../competitor-intel) | | Generating new ad creative based on what you found | [ad-creative-generation](../ad-creative-generation) |

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Apify integration connected at https://app.hyperfx.ai/integrations — the Meta Ads Library tools run via Apify under the hood.

If search_facebook_ads is not in the tool list, stop and tell the user to enable Hyper MCP and connect Apify.

Tool surface

| Tool | Purpose | | --- | --- | | search_facebook_ads | Search the Meta Ads Library by keyword. Returns compact results (title, body, CTA, link, page name, dates, platforms). Max 40 per call. | | get_facebook_ad_details | Get full details for a specific ad. Requires both ad_archive_id and page_id — both come from search_facebook_ads results. | | search_facebook_ads_enriched | Search + enrich each result with page contact info (email, phone, website). Slower (multiple API calls per result). Max 20 per call. | | search_facebook_pages | Search Facebook pages by category + location (not by keyword). Useful for building a lead list from a vertical. | | scrape_facebook_pages | Scrape detailed data from specific Facebook page URLs. |

Critical rules

1. Public-only data. The Meta Ads Library is public. Don't attempt to bypass any access control or scrape private content.
2. Count limits differ between tools. search_facebook_ads allows count up to 40. search_facebook_ads_enriched caps at 20 — exceeding this returns an error.
3. get_facebook_ad_details needs two IDs. Both ad_archive_id and page_id are required. Both are returned in every search_facebook_ads result row — pass them through together.
4. Enriched search is slow. It makes a Facebook page scrape per ad and optionally a website scrape. Only use it when contact info matters (lead-gen workflows). For pure ad intelligence, use the regular search_facebook_ads.
5. Apify-backed tools fail intermittently. Expect occasional "fetch failed" responses. Retry once after a short delay before reporting the source as missing.
6. Don't over-interpret a single ad. "Brand X is running a discount" is noise. "5 of the top 10 advertisers in this query are running discounts" is signal. Always aggregate before drawing conclusions.

Workflow

Phase 1 — Define the query

Before running anything, agree on:

1. The search query — keyword(s) competitors would target. Examples: "meal kit delivery", "AI marketing tools", "skincare for sensitive skin".
2. Country — ISO code (e.g. "US", "GB", "AU"). Default to "ALL" only if the user explicitly wants global.
3. Active vs all — active_status="active" is usually what you want. Inactive ads are historical and noisier.
4. Time window — period accepts "last24h", "last7d", "last14d", "last30d", or "all_time". Match the window to the user's intent (weekly digest → "last7d", trend research → "last30d").
5. The job — what is this for?
6. Creative trend report → use search_facebook_ads, summarize patterns across hooks, CTAs, formats.
7. Top advertiser snapshot → use search_facebook_ads, group by page_name.
8. Lead list → use search_facebook_ads_enriched, filter for rows with contact_email or contact_website.

Phase 2 — Pull the ads

search_facebook_ads(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=40,                # max for this tool
    period="last30d"
)

Each result row includes: ad_archive_id, page_id, page_name, is_active, start_date_formatted, end_date_formatted, title, body, cta_text, link_url, caption, ad_library_url, page_categories, publisher_platform.

For more than 40 ads, paginate by re-calling with offset=40, offset=80, etc.

For lead-gen with contact info:

search_facebook_ads_enriched(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=20,                # max for the enriched tool
    scrape_websites=True,
    filter_spam=False
)

Enriched rows add: contact_email, contact_phone, contact_website, page_followers, page_rating, address, business hours.

Phase 3 — Get full creative for the most interesting ads (optional)

search_facebook_ads returns truncated bodies for some ads. To get the complete creative — including video URLs and images — call get_facebook_ad_details on the specific ads worth a deeper look:

get_facebook_ad_details(
    ad_archive_id="559220927273823",      # from search results
    page_id="328127803978438"             # from search results
)

Both args come from the same row in search_facebook_ads. Do this for the top 3–5 ads, not all 40 — each detail call is a separate Apify run.

Phase 4 — Surface the intelligence

Present the findings inline in chat. Pick the format that matches the user's job from Phase 1.

Top advertisers (group by page):

| Page | Active ads | Categories | Notable angle | | --- | --- | --- | --- | | Brand A | 12 | Restaurant, Meal Kit | "Skip the grocery store" hook in 8/12 ads | | Brand B | 7 | Software, Subscription | Heavy on UGC video, "$1 first week" offer |

Common CTAs and hooks:

| Pattern | Count | Examples | | --- | --- | --- | | Sign up CTA | 18 | … | | Shop now CTA | 12 | … | | Price-anchor opener ("From $X/week") | 9 | … | | Founder-story opener | 4 | … |

Recently launched ads (last 7 days):

| Page | Started | CTA | Hook | Library URL | | --- | --- | --- | --- | --- | | Brand A | 2026-04-28 | Sign up | "Skip the grocery run this week" | <ad_library_url> |

Lead list (enriched only):

| Page | Email | Website | Followers | Active ads | | --- | --- | --- | --- | --- | | Brand A | hello@a.com | a.com | 12K | 7 |

Phase 5 — Recurring monitoring (optional)

If the user wants ongoing tracking:

1. Save the query, country, and active_status settings.
2. Re-run weekly with period="last7d".
3. Brief becomes a delta report — new ads since the last run, advertisers that changed posting cadence, CTA / offer shifts.

This is when [competitor-intel](../competitor-intel) becomes the better skill — it handles multi-source diffing across many surfaces, not just Meta ads.

Output standards

• Always cite the ad_library_url for any specific ad referenced in the brief — the user can click through to verify.
• Aggregate before quoting. Don't paste raw ad bodies; extract the pattern and quote 1–2 representative examples.
• Mark interpretation explicitly. "Observation: 8 of 10 top advertisers use a 'first week free' offer. Possible interpretation: …".
• Note the time window. Every brief should state the search query, country, and date range it was generated from.