The AdSpyfy manual.

1. What AdSpyfy is

AdSpyfy is a Chrome side panel that reads the public ad libraries you are already browsing — the Meta Ad Library and the Google Ads Transparency Center — and turns what is on screen into a searchable local database of ads.

The one signal it is built around: how long an ad has been running. An advertiser who keeps paying to run the same creative for 300 days is telling you it works. AdSpyfy captures that run length, sorts by it, and lets you slice the result.

What it does not do:

• It does not use Meta or Google private APIs, and it never asks for your Facebook login.
• It does not crawl in the background. It reads the page you have open, while you have it open.
• It does not upload your harvested ads anywhere. Everything lives in your browser.
• It does not give you performance data Meta and Google do not publish. Run length, active status and (where published) reach or spend ranges are real; revenue, ROAS and CTR are not available anywhere in AdSpyfy because they are not public.
• It ships no AI key of its own. AI features use your key, stored in your browser.

2. Install and first run

The extension is not on the Chrome Web Store yet, so it installs unpacked:

1. Download the AdSpyfy ZIP and unzip it to a folder you will keep (not Downloads/Temp).
2. Open chrome://extensions.
3. Turn on Developer mode (top right).
4. Click Load unpacked and select the unzipped folder.
5. Pin AdSpyfy to the toolbar so the icon is one click away.

To open the panel: click the AdSpyfy toolbar icon, or press Alt+Shift+A. The panel opens on the right of the current tab and stays with that window.

Permissions, in plain terms: the extension reads facebook.com/ads/library and adstransparency.google.com pages, plus the creative-hosting domains those pages use, so it can show and download creatives. It asks for access to an AI provider's domain only when you save that provider's key, and for a specific advertiser landing page only when you click Archive landing page.

3. Your first harvest in five steps

1. Open https://www.facebook.com/ads/library/, choose a country and search a keyword or an advertiser page.
2. Press Alt+Shift+A to open the AdSpyfy panel.
3. Scroll the Meta results, or click Start auto-scroll in the panel and let it page for you.
4. Watch the header counters: captured (ads stored), longest run (the longest run length seen) and in view (how many pass your current filters).
5. Set Sort to Longest running and read from the top. Those are the creatives your competitor has kept paying for.

If nothing appears: make sure you are on the Ad Library results page (not the landing form), and reload the tab once after installing — content scripts only attach to pages loaded after the extension was installed.

4. The panel at a glance

Four tabs across the top:

• Harvest — everything you have captured, with the search box, filters, exports and the tools sections.
• Swipe file — the ads you deliberately saved, with boards, tags and notes (Lifetime).
• Compare — advertiser leaderboard, side-by-side comparison, angle coverage and hooks library.
• Settings — AI provider and key, licence, MCP export, storage.

Under the tabs sit three counters (captured / longest run / in view) and a notice line that reports capture status, plan limits and errors.

5. Search: the syntax in full

The search box filters the ads you have already captured. It never sends a query to Meta or Google — that is what the Deep link builder does (see §14).

The rules, exactly as the code applies them:

• A plain word includes. luggage keeps only ads whose text contains luggage.
• A word starting with - excludes. -kids removes every ad containing kids.
• Multiple terms are ANDed. luggage sale -kids -toddler keeps ads containing both luggage and sale and containing neither kids nor toddler.
• Space is the separator. So free shipping is two separate terms — an ad must contain free and shipping anywhere, in any order, not the phrase.
• Use a semicolon when you want a phrase. If the box contains a ; anywhere, AdSpyfy splits on semicolons instead of spaces and each segment is one term, spaces included. free shipping; -cash on delivery means: text must contain the phrase free shipping and must not contain the phrase cash on delivery.
• Quotes are not syntax. Typing "free shipping" searches for the quote characters too. Use the semicolon form instead.
• Matching is case-insensitive and matches anywhere inside a word — ship matches shipping, and -ship will also remove shipping.
• The hyphen is only special at the start of a term. t-shirt is a normal include term; -t-shirt excludes t-shirt.
• Empty terms are ignored, so stray spaces or a lone - do nothing.

Which text is searched. Advertiser / page name, primary body text, headline, link description and the CTA button text. Notes and tags are not searched here — the Swipe file tab has its own search that covers notes and tags.

Recipes

6. Filters and sorting

All filters combine (AND), and every export and tool section obeys them — what you see in view is what gets exported.

• Status — All / Active / Inactive. Active means the library still shows the ad as running.
• Source — All / Meta / Google. Ads captured before source tracking count as Meta.
• All searches — scopes to one saved harvest query, so you can keep several research sessions in one database and look at them separately.
• Advertiser — one advertiser at a time.
• Lifecycle — Proven winners / Killed tests / Scaling / Testing / Ended / Running / Unknown. Definitions in §7.
• Sort — Longest running (default), Shortest running, Recently seen, Impression rank.
• Collapse reused creatives — one row per creative that appears many times, instead of every duplicate. Useful when an advertiser runs the same asset across dozens of ad IDs.

Two filters get set for you when you click into a tool: choosing a creative wave scopes the list to that advertiser + launch day, and clicking a cell in the angle grid scopes it to that angle family and hook type. Both clear from the same place you set them.

Note on Impression rank: it only exists for ads captured while Meta itself was sorting by impressions. Build a link with the "Top impressions" preset in the Deep link builder, harvest from it, and AdSpyfy records the position Meta showed each ad in. It is a ranking Meta published, not an impression count.

7. Lifecycle labels: what each one means

Computed from two public facts only — whether the ad is still active, and how many days it has been running:

These are heuristics from duration, not proof of profit. An ad can run long for brand reasons, and a killed test can be a budget or compliance casualty.

8. Reading an ad card

Each card shows the advertiser, run length in days, status, source, lifecycle badge, the creative preview, the primary text and the actions below. Open Analytics on a card for:

• Run so far and the run timeline AdSpyfy has observed across visits.
• Advertiser median and best run length, with a Best so far badge and a +Nd vs median delta when the ad is the advertiser's longest.
• Variants in the ad (carousel cards) and how many other captured ads reuse the same creative.
• Reach and spend ranges, EU reach breakdown, payer/beneficiary and targeted countries — only where the library publishes them, and only for ads where AdSpyfy captured that panel.
• Impression rank, when the ad was captured under Meta's impressions sort.

Card actions: Download creative (single file), Save to swipe file, Analyse (AI), Transcribe (video, AI), Archive creative, Archive landing page, Watch advertiser, and the landing URL when the library exposed one.

9. Auto-scroll and rate limits

Start auto-scroll paces the Ad Library page for you and captures as it goes; the button turns into Stop auto-scroll and its state survives closing the panel.

Meta rate-limits heavy paging. When that happens AdSpyfy stops auto-scroll by itself and the notice says "Auto-scroll stopped because Meta rate-limited the page", with a cooldown countdown. That is Meta throttling your IP, not a bug: wait for the cooldown, then continue. Deep pagination into thousands of results depends entirely on how tolerant your IP and account are, so treat very large single-session harvests as unproven.

10. Google Ads Transparency Center

Open https://adstransparency.google.com/, search an advertiser, and captures flow into the same harvest with Source = Google. Google publishes a different set of fields to Meta — expect first/last-shown dates and formats rather than Meta's reach and EU panels — so some analytics rows stay empty on Google ads. Use the Source filter to keep the two apart when comparing.

11. Creative test waves

Ads grouped by advertiser + launch day. Each wave shows the date, how many ads launched that day, how many are still active, the longest run in the wave and the lifecycle mix. This is how you see a competitor's testing rhythm: a wave of eight launched on one day with one survivor tells you what they kept. Click a wave to filter the harvest to it. Ads without a usable start date are counted as ignored rather than guessed into a wave.

12. Swipe file, boards, tags, notes

Lifetime feature. Save on any card copies it into the Swipe file tab, where each record gets:

• a Board (create boards like "Client A – Q4" and assign records to one),
• Tags — free text plus one-click chips from a fixed taxonomy: winner, testing, killed, ugc, testimonial, demo, founder-story, discount, bundle, urgency, festive, comparison, problem-agitate, listicle, b2b, retargeting,
• a Note — free text, saved as you type,
• Remove — deletes that record.

The Swipe file search box covers saved ad text, notes and tags together, and the board/tag chips filter on top of it. Your saved records stay readable even if a licence lapses.

13. Saved searches, watchlist and alerts

• Save this search stores the current query and filters under a name (Lifetime). Re-run reopens the search so you can capture the current state of that market; the row shows when it last ran and how many ads it found.
• Watch advertiser on a card adds them to the watchlist. When you next revisit Ad Library pages and AdSpyfy sees new ads for a watched advertiser, you get a Chrome notification. It does not poll in the background.
• A weekly digest notification nudges your saved searches roughly every seven days.

14. Deep link builder

This is the opposite of the search box: it builds a Meta Ad Library URL with Meta's own filters, which is how you use filters Meta applies server-side. Fields: search terms, search type (keyword / exact phrase / advertiser page), country code, active status, ad type (all or political/issue), media type (images, memes, images+memes, videos, no image or video), publisher platform (Facebook, Instagram, Audience Network, Messenger, WhatsApp, Threads), content language (24 languages including English, Hindi, Spanish, Portuguese, French, German, Arabic, Indonesian, Japanese, Bengali, Tamil, Telugu, Marathi, Urdu), country-targeting mode, advertiser page ID, impression date range, an impression preset (top impressions — all time / 7 / 30 / 90 days) and sort by impressions.

Copy puts the URL on your clipboard; Open loads it in a tab, ready to harvest. Invalid combinations are explained inline instead of producing a dead link. The same builder is on the website: /tools/ad-library-url-builder.html.

Platform, media type and language are Meta-side filters here — the panel's local filters are the ones listed in §6.

15. Compare tab

• Advertiser leaderboard (free) — every advertiser in your harvest ranked by longest observed run, with counts per lifecycle stage.
• Compare selected (Lifetime) — pick up to four advertisers for a side-by-side: run lengths, active/inactive mix, waves and hooks.
• Angle coverage — a grid of angle family × hook type built from your AI analyses, showing which persuasion angles a market is saturated with and which are empty. Click a cell to filter the harvest to it.
• Hooks library — every analysed hook in one list with run length, lifecycle and hook type, sorted by run length or recency. This is the fastest way to brief a copywriter: the hooks that survived longest, in one screen.

16. Exports and downloads

Downloads are single-file and free; bulk exports are Lifetime. Every export uses your current filters and selection, so filter first, then export.

• Download creative on a card saves one file named advertiser_startdate_adid_index.jpg|mp4.
• Export ZIP → adspyfy-export.zip containing ads.json, ads.csv and every creative, named with the same convention. If a creative cannot be fetched, the ZIP includes export-report.txt listing each failure with its reason.
• Export CSV → adspyfy-export.csv with columns id, source, pageName, isActive, daysRunning, mediaType, bodyText, landingUrl.
• Export JSON → adspyfy-export.json, the full records including analyses and transcripts where present.
• Select all shown / Clear selection control which ads bulk actions apply to; the counter shows the current selection.
• Archive filtered stores the filtered creatives locally (see §17). Clear harvest deletes the ad pool and asks for a second click to confirm.

17. Creative archive and storage

Creatives on Meta and Google expire. Archive creative (or Archive filtered) copies the file into local storage so the card keeps working after the source URL dies. Settings shows the archive size, and warns above 500 MB. Archive landing page saves the advertiser's destination page as plain-text source — displayed as source, never re-opened as a live page — and needs the one-off permission Chrome asks for. Some destinations block it; that is the site's choice, not a failure in the extension.

18. AI analysis with your own key

Lifetime feature, bring your own key. Settings → AI provider:

• Claude (Anthropic), Gemini, Groq, OpenAI, OpenRouter, Cloudflare Workers AI (which also needs your account ID).
• Leave Model empty for the newest available model, or pick one; Refresh models pulls the live list from your provider.
• Save key locally stores the key in this browser only. It goes to the provider you chose and nowhere else — never to AdSpyfy's licence endpoint. Test connection proves the key works before you spend on a batch.

Analyse on a card, or Analyse selected for a batch (with a Stop button), returns a structured read per ad: the hook and its type, the angle and angle family, the offer, the audience, emotional triggers, CTA strength, format notes, a 1–10 scroll-stopper score with a reason, why it works, weaknesses, a "steal this" action, tags, hook delivery, confidence and notes. Results are stored with the ad, so they feed the hooks library, angle grid, exports and MCP.

Cost is yours and depends on your provider's pricing; analysis runs one ad at a time so you can stop at any point.

19. Video transcription

Transcribe sends the video creative to your AI provider and stores the transcript with the ad, so analysis can quote the words actually spoken in the first seconds — usually the real hook.

Limits, as enforced: transcription needs Gemini, OpenAI or Groq. Claude, OpenRouter and Cloudflare Workers AI have no audio endpoint and the panel says so instead of failing silently. Maximum creative size is 20 MB, and Gemini's inline path caps at 14 MB — use OpenAI or Groq for larger videos.

20. Connect Claude, Cursor and other AI clients (MCP)

Lifetime feature. This lets you ask your harvest questions in Claude Desktop or Cursor — "what is the longest-running ad in my luggage harvest and what is its hook?" — with the answer coming from your own captured data.

Why it is a separate download. MCP clients connect to a server over stdio or HTTP. A Chrome MV3 extension cannot listen on a port or spawn a process, so the browser half (the export, the gating) is in the extension and the tiny server that Claude talks to runs on your machine. Nothing is uploaded: the server reads your exported file from disk, read-only.

Setup (once)

1. Settings → Export data for MCP → save adspyfy-mcp.json.
2. Unzip the adspyfy-mcp package, then cd into it and run npm install (Node.js 20 or newer).
3. Add this to Claude Desktop's or Cursor's MCP config:

{
  "mcpServers": {
    "adspyfy": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/bin/adspyfy-mcp.js", "--data", "/absolute/path/to/adspyfy-mcp.json"]
    }
  }
}

1. Restart the client and ask it something. Export again whenever you want fresh data — the server reloads the file when it changes, no restart needed. Without --data it uses ADSPYFY_MCP_DATA, then the newest adspyfy-mcp.json in your Downloads folder.

The eight tools it exposes (all read-only): adspyfy_status, search_ads, get_ad, top_longest_running, advertiser_summary, creative_test_waves, hooks_library, search_swipe_file. search_ads uses the same keyword, status, source, advertiser and run-length rules as the panel — including -word exclusions.

Two different things worth keeping straight: Claude BYOK analyses one ad inside the panel using your Anthropic key; MCP lets Claude query your whole harvest locally. You can use either, both, or neither.

21. Prompt library

Lifetime includes the AdSpyfy prompt library: ready-to-paste prompts for the MCP tools above, for in-panel BYOK analysis, and for turning what you find into briefs, scripts, copy variants and client reports. A free sample is public; unlock the full library with your licence key at /prompts, or download it as Markdown or JSON to keep beside your work.

22. Licence, devices and the free plan

• Free stores up to 1,000 ads. Past that, AdSpyfy keeps the 1,000 most recently seen and drops the oldest, and the notice tells you it happened. Nothing you saved to the swipe file is affected.
• Lifetime removes the cap and unlocks exports, swipe file and boards, saved searches, archive, watchlist, advertiser comparison, AI analysis, transcription, MCP and the prompt library.
• Activate in Settings → paste your key → Activate Lifetime. Deactivate this device frees a slot.
• Three devices per licence. Activating a fourth removes the oldest activation.
• The licence endpoint stores only the key, tier, device count, activation timestamps and a random device UUID. It never sees your ads, notes, searches or AI key.
• Offline is fine: an activation is valid for 30 days and keeps working for a further 14-day grace period without a check-in.

Lifetime is $99, paid once. Checkout runs through Dodo Payments and your licence key is issued automatically on the confirmation page and emailed to the address you paid with; paste it into Settings → Activate Lifetime. Keys can also be issued manually by support.

23. Privacy in one paragraph

Your harvest, notes, tags, archives and AI keys live in your browser's local storage. Network calls go only to the pages you are browsing (Meta, Google, their creative hosts), the AI provider you chose, the specific landing page you asked to archive, and the licence endpoint — which receives a licence key and a random device UUID and nothing else. No analytics, no telemetry, no tracking, no data sale. Full text: Privacy.

24. Troubleshooting

25. Honest limits

• Not on the Chrome Web Store yet; installs unpacked.
• Checkout runs through Dodo Payments; licence keys are issued automatically after a successful payment, with manual support issuance still available.
• Deep pagination into very large result sets depends on Meta's rate limiting of your IP; it is not proven at scale from our side.
• A successful Claude completion has not been verified with a paid Anthropic key. The request path, headers and error handling are verified (a real call returns a clean invalid-key error).
• Google's published fields are thinner than Meta's, so some analytics rows are empty on Google ads.
• Landing-page archiving depends on the destination allowing the request.
• Run length is a survival signal, not a performance metric. AdSpyfy will never claim otherwise.

26. Glossary

Harvest — the local pool of captured ads. Run length / days running — days between the ad's published start date and now (or its last seen active date). Lifecycle — the label from §7. Wave — ads from one advertiser launched on the same day. Reuse group — captured ads sharing the same creative. Angle family — the buying motivation an ad leans on. Hook type — the shape of the opening line. BYOK — bring your own key. MCP — Model Context Protocol, how Claude/Cursor query local tools.