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](https://app.hyperfx.ai/mcp) - **Apify integration connected** at [https://app.hyperfx.ai/apps](https://app.hyperfx.ai/apps) — 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? - **Creative trend report** → use `search_facebook_ads`, summarize patterns across hooks, CTAs, formats. - **Top advertiser snapshot** → use `search_facebook_ads`, group by `page_name`. - **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.