AI Ad Analysis at Scale: Enriching Competitor Ad Creatives via API

Your creative team has 200 competitor video ads sitting in a folder of screenshots and screen recordings. Watching all of them, tagging hooks by hand, and pasting quotes into a deck is a week of work nobody will repeat next month. AI ad analysis through an API changes the shape of that job entirely. Each ad goes in as a JSON object and comes back as structured creative intelligence: hook type, claims, audience signals, creative structure, even a rebuild-ready brief.

TL;DR: The AdLibrary API's /api/enrichment endpoint runs a Gemini-powered teardown on any ad and returns a timestamped transcript, a strategic read, a persuasion analysis, and a 1:1 replication brief as structured data. Cost is 1 credit per ad for text, images, and videos up to 180 seconds, with a published formula for longer videos. Re-running an ad you already analyzed costs zero. Chain it behind /api/search and 200 competitor ads become a queryable dataset in an afternoon instead of a week of watching.

That is the whole pitch of this article. Not "AI will transform your workflow" in the abstract, but a concrete pipeline: one search call to find the ads, one enrichment call per ad to extract the creative DNA, one LLM pass at the end to turn rows into a pattern report. You will see the exact requests, the exact costs, and the places where the machine still gets it wrong.

What AI Ad Analysis Actually Extracts

The enrichment endpoint does the work a senior creative strategist would spend an afternoon on per ad. Point it at a creative and the response contains four layers of analysis.

The transcript. Everything spoken and shown, scene by scene, with timestamps. For a 45-second UGC ad, that means the spoken dialogue, the on-screen text overlays, and the visual beats in order. This alone replaces the watch-pause-type loop that eats most of a manual review.

The strategic read. The product being sold, the funnel stage the ad targets, the awareness level it assumes, who it is talking to, and the core message. These are the audience signals a creative strategist usually infers from context, written out as fields.

The persuasion teardown. The hook and why it stops the scroll, the offer architecture, the proof stack, and the psychological levers in play, with each point quoted from the ad itself. This is where copy themes surface. Run it across 40 ads from one advertiser and the recurring claims become impossible to miss.

The replication brief. The part nobody wants to write by hand. The analysis detects the format and produces a 1:1 rebuild spec tuned to it. Image ads get a full generation prompt with composition, color, and text overlays. UGC videos get a character spec, five hook variations, and a clip-by-clip shoot script. Cinematic ads get a shot list with per-scene prompts plus music direction.

The response shape is simple:

{
  "enrichment": {
    "analysis": "Full strategic and persuasion teardown...",
    "summary": "Condensed creative read...",
    "transcription": "Scene 1 (0:00-0:03): Creator holds product to camera...",
    "source": "gemini"
  },
  "cached": false,
  "alreadyUnlocked": false,
  "balance": 412,
  "creditsUsed": 1
}

Four text fields, two cache flags, and your remaining credit balance. Everything downstream in this guide is built on that object.

Step 0: Pull the Ads Before You Analyze Anything

AI ad analysis is only as good as the ads you feed it. Before any enrichment call, you need a defensible set of creatives, and that starts with /api/search, the same multi-platform search that powers the AdLibrary app.

One request fans out across Facebook, Instagram, TikTok, YouTube, Google, LinkedIn, and the rest of the 11 covered platforms, and returns ads with copy, creative URLs, engagement counts, impressions, runtime, and a spend estimate:

curl -X POST "https://adlibrary.com/api/search" \
  -H "Authorization: Bearer adl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "collagen supplement",
    "appType": "3",
    "platform": ["facebook", "instagram"],
    "adsType": ["2"],
    "sortField": "-days",
    "daysBack": 90,
    "geo": ["USA"]
  }'

The filters here are doing creative-research work. adsType: ["2"] restricts to video, where most competitor spend concentrates. sortField: "-days" puts the longest-running creatives first, and runtime is the most reliable single signal that an ad converts, because advertisers kill losers in week one. The search response includes a total count, so you know the size of the market you are sampling from.

Each search costs 1 credit per page and returns up to 60 ads, with a rate limit of 10 requests per minute. For a deeper playbook on building competitor sets, the competitive creative analysis guide and how to monitor competitor ads cover keyword and brand-based discovery in detail.

Two response fields deserve a warning before you build logic on them. Impressions come back as bands rather than precise counts, so treat them as ranges. And spend is always an estimate, never a reported figure. If you want to pressure-test a spend estimate against your own market assumptions, the ad spend estimator is the manual version of the same math.

The Single-Ad Pipeline: One Call, One Teardown

Start small. The single-ad workflow is two requests: search for the ad, enrich it.

Take one result object from the search response and pass it to the enrichment endpoint. The ad_key and platform fields are required, and the more context fields you include (copy, media URLs, engagement), the better the analysis:

curl -X POST "https://adlibrary.com/api/enrichment" \
  -H "Authorization: Bearer adl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ad": {
      "ad_key": "meta_1234567890",
      "platform": "meta",
      "advertiser_name": "Acme Wellness",
      "body": "I replaced my entire morning routine with one scoop...",
      "video_url": "https://..."
    }
  }'

Twenty to sixty seconds later you have the full teardown. For a creative team lead, this single call already replaces a real task: the "can you break down this competitor ad for Thursday's meeting" request that normally costs someone an hour. The output drops straight into a creative brief with quotes already pulled.

The single-ad pipeline is also the right way to validate quality before you spend on a batch. Enrich three ads you know well. Read the analyses against your own judgment. If the hook classification and the strategic read match what your team would say, scale up. If you want this loop inside an agent rather than a terminal, the Claude Code workflow guide and the MCP server build show two ways to wire it in.

Batch Enrichment: 200 Ads Into a Queryable Dataset

The batch pipeline is the same two calls in a loop, plus discipline about rate limits and credits. Here is a complete working version in Python:

import time, json, requests

KEY = "adl_your_api_key"
H = {"Authorization": f"Bearer {KEY}"}

search = requests.post(
    "https://adlibrary.com/api/search",
    headers=H,
    json={
        "keyword": "collagen supplement",
        "appType": "3",
        "adsType": ["2"],
        "sortField": "-days",
        "daysBack": 90,
    },
).json()

# Only enrich ads with >= 30 days of runtime (proven spend)
candidates = [a for a in search["results"] if a.get("days_count", 0) >= 30]

rows = []
for ad in candidates:
    r = requests.post(
        "https://adlibrary.com/api/enrichment", headers=H, json={"ad": ad}
    ).json()
    rows.append({
        "ad_key": ad["ad_key"],
        "advertiser": ad.get("advertiser_name"),
        "platform": ad.get("platform"),
        "runtime_days": ad.get("days_count"),
        "summary": r["enrichment"]["summary"],
        "analysis": r["enrichment"]["analysis"],
        "transcript": r["enrichment"]["transcription"],
        "credits_used": r["creditsUsed"],
    })
    time.sleep(3)  # stay under the 20/min enrichment limit

json.dump(rows, open("enriched_ads.json", "w"), indent=2)
print(f"{len(rows)} ads enriched, balance: {r['balance']}")

A few deliberate choices in that script. The runtime filter means you only pay to analyze ads that have survived at least a month of spend, which is the cheapest creative testing signal available: the competitor already ran the test for you. The time.sleep(3) keeps you under the enrichment endpoint's 20 requests per minute. And every row stores credits_used, so the run is self-auditing.

For 200 ads the arithmetic is straightforward. Four search pages cost 4 credits. Two hundred enrichments cost 200 credits if every video is 180 seconds or shorter, more if some run long (the formula is in the next section). On the Business plan's 1,000+ monthly credits, a full 200-ad market scan is about a fifth of the month's allowance, repeatable weekly at smaller scale for ongoing monitoring.

The output file is the asset. enriched_ads.json is a structured winning ad elements database your team can grep, sort in a spreadsheet, or load into an LLM, and it compounds with every run.

Caching Economics: When AI Ad Analysis Costs Nothing

The enrichment endpoint has two cache layers, and confusing them is the most common billing surprise in batch ad analysis. The response flags tell you exactly which one fired.

alreadyUnlocked: true means free. Once you have paid to enrich a specific ad, that analysis belongs to your account permanently. Every repeat call for the same ad returns instantly at zero credits. This is the flag that makes iterative workflows cheap: your pattern-report script can re-pull all 200 analyses tomorrow or after a refactor, and the re-pull costs nothing.

cached: true alone still costs 1 credit. If another customer already enriched an ad, the shared analysis cache is reused and the Gemini run is skipped, so you get a fast response. But it is the first time you are accessing that ad's analysis, so you are still charged the standard credit. Cached means faster, never free. Only alreadyUnlocked means free.

The practical consequences for a creative team:

1. Never delete your enriched dataset and re-run blind. Repeats of already-unlocked ads are free, so re-pulling is safe, but your local JSON file is still faster than 200 API calls.
2. Dedupe on ad_key before enriching. The same creative often appears across multiple searches. The key is the stable identifier, so a seen-before check saves real credits on overlapping keyword sets.
3. Use force: true sparingly. It bypasses both caches and re-runs the full analysis fresh. Useful when an ad's creative was updated, wasteful as a default.

This caching design rewards exactly the behavior a research team wants anyway: build one canonical dataset, append to it, and treat every previously analyzed ad as a sunk cost that keeps paying out.

Video Duration Cost Math: Budget Before You Run

Text and image ads cost a flat 1 credit to enrich. Video pricing follows duration:

credits = 1                               (video <= 180 seconds)
credits = 1 + ceil((duration - 180) / 60) (longer videos)

Worked examples: a 90-second UGC ad costs 1 credit. A 179-second ad costs 1. A 181-second ad tips to 2. A 5-minute advertorial at 300 seconds costs 3.

One detail matters for anyone budgeting a batch: the duration is derived server-side from the transcription itself. Whatever duration value you pass in the request is ignored for billing, so there is no way to under-report a long video, and no risk of being overcharged by a wrong metadata field either.

The lever you control is the search filter. Adding videoDurationEnd: 180 to your search keeps every candidate inside the 1-credit tier, which turns the 200-ad scan into a predictable 204 credits flat. If long-form ads are the actual research target, sample them deliberately: ten 300-second advertorials cost 30 credits, the same as thirty short ads, and you should decide that trade consciously rather than discover it on the invoice. Since long videos correlate with expensive production, pairing this with a CPM calculator view of your own media plan helps decide whether long-form is even a format worth copying in your account.

From Enriched Rows to Pattern Reports with an LLM

Individual teardowns are useful. The compounding value shows up when you analyze the analyses. Two hundred structured creative reads are small enough to fit in a single LLM context window, and that is where screenshot folders could never go.

The workflow: load enriched_ads.json, concatenate the summaries and analyses, and prompt a model for cross-ad patterns. A prompt that works well in practice:

You are a creative strategist. Below are AI teardowns of 187 video ads
from the collagen supplement market, each with runtime_days as a
performance proxy.

1. Cluster the hooks into types. For each type: count, median
   runtime_days, and two quoted examples.
2. List the 5 most repeated claims across advertisers, with who
   makes them.
3. Identify creative structures (e.g. testimonial -> demo -> offer)
   and which structure the longest-running ads share.
4. What angle is conspicuously absent from this market?

Question 4 is the one that earns the report its audience. Clustering tells you what the market does. The absence analysis tells you what to make next, and feeds directly into an AI creative iteration loop where the gap becomes the next test.

Because the enrichment output is consistent structured text rather than 187 differently formatted notes, the LLM's clustering is dramatically more reliable than it would be on raw transcripts. The teardown already normalized every ad into the same analytical frame. Your model is comparing like with like.

Teams running this inside an agent take it further: Claude Code can run the whole loop, from search to enrichment to report, and a structured briefs workflow turns the winning clusters into production-ready briefs. That is AI ad analysis as a standing capability rather than a one-off project.

Choosing Which Ads Deserve Enrichment

Credits are an AI ad analysis budget, and the fastest way to waste them is enriching everything that matches a keyword. Three selection strategies, in increasing order of sophistication:

Runtime threshold. The batch script above already does this: days_count >= 30 means a competitor kept paying for the ad for a month. Simple, and it works. The logic behind it is laid out in how to reverse-engineer winning ads.

Engagement floors. Add likeBegin and commentBegin thresholds to the search itself so low-traction ads never reach your candidate list. This filters at search time, costing nothing extra. High comment counts also flag ads worth reading manually, which remains one of the most underrated sources of creative angle intelligence.

Winners scan. For a single advertiser, the winners endpoint scores their entire portfolio and returns only the creatives with evidence of scaled spend, with plain-language reasons like "Runtime 89 days, top 10% of this advertiser" and side-by-side deltas against losing variants on the same landing page. A scan costs a flat 10 credits and auto-refunds if it errors or finds nothing. Enriching only the winners from a scan is the highest signal-per-credit configuration the API offers: the scan finds the proven concepts, enrichment explains why they work.

Whichever selector you use, the goal is the same. Spend search credits broadly and enrichment credits narrowly, on ads where the market has already voted with budget. Track your hook-rate benchmarks separately so you know what "good" looks like when the report lands.

What AI Ad Analysis Still Gets Wrong

A Gemini-powered teardown is a strong junior strategist, not an oracle. Five failure modes show up consistently, and a team lead should check for all of them before a report drives spend decisions.

Audience inference is a guess, not delivery data. The model infers targeting from casting and language cues in the creative. An ad starring a 55-year-old may still be delivered mostly to 35-year-olds. Treat the strategic read as the intended audience, and validate against actual performance signals where the platform exposes them.

It cannot see why an ad performed. Enrichment explains what an ad does, never what it achieved. The performance proxies live in the search result (runtime, engagement, impression bands, estimated spend), and joining the two is your job. An eloquent teardown of a loser reads exactly as convincingly as one of a winner, which is why the selection step matters so much.

Irony and culture-specific hooks misread. Deadpan humor, deliberately bad production as an aesthetic choice, and meme formats sometimes get classified at face value. If your market runs heavily on in-jokes, expect to reclassify a percentage of hooks by hand.

Transcription degrades on chaotic audio. Heavy music beds, overlapping speakers, and rapid-cut compilations can produce gaps or misheard lines. The timestamped structure usually survives, but quote anything load-bearing only after checking the source video.

Replication briefs inherit the source ad's flaws. A 1:1 rebuild brief faithfully reproduces a mediocre structure if you feed it a mediocre ad. The brief is a floor for production speed, never a substitute for ad-fatigue judgment about whether the concept deserves rebuilding at all.

None of these are reasons to stay manual. They are reasons to keep a human review pass between the pattern report and the production calendar, exactly where senior judgment is highest-value anyway.

Where Meta's Free API Fits (and Where It Stops)

Credit where due: Meta's Ad Library API created this entire category. It is free, official, and the right tool if your research fits the ads it covers, which means political and social-issue ads in most regions, with all ad types available for the EU and UK. If that scope matches your work, use it and pay nothing.

For commercial creative research it stops short in three places. Coverage: most commercial ads outside the EU/UK windows simply are not in it, and Google's Ads Transparency Center and the LinkedIn Ad Library are separate manual tools with their own scopes, not unified endpoints. Signals: no engagement counts, spend estimates, or creative scoring on commercial ads. Analysis: the API returns the ad, and the AI ad analysis layer in this article you would build yourself, likely on Google's own Gemini video understanding stack, which is precisely the engineering the enrichment endpoint packages behind one call.

The honest framing: Meta's free API is fine for one platform. The moment you want TikTok, YouTube, or LinkedIn creatives in the same dataset, with performance signals and AI analysis attached, you need a paid layer on top. That is the slot the AdLibrary API fills: one adl_ key, no app review, eleven platforms, and the enrichment layer built in. A full ad intelligence stack rather than a transparency archive.

Frequently Asked Questions

What does AI ad analysis extract from a competitor ad?

The AdLibrary enrichment endpoint returns four layers per ad: a timestamped scene-by-scene transcript, a strategic read (product, funnel stage, awareness level, target audience, core message), a persuasion teardown (hook, offer architecture, proof stack, psychological levers, with quotes), and a format-specific 1:1 replication brief for rebuilding the ad with AI tools.

How much does it cost to analyze 200 competitor ads via the API?

About 204 credits: 4 credits for four search pages (60 results each) plus 1 credit per enrichment for text, image, and video ads up to 180 seconds. Longer videos cost 1 + ceil((duration − 180)/60) credits, so a 300-second ad costs 3. Filtering search results to videos under 180 seconds keeps the batch flat-rate.

Do I pay again if I re-analyze the same ad?

No. Once your account has enriched an ad, repeat calls return alreadyUnlocked: true and cost zero credits permanently. A shared-cache hit (cached: true) on an ad you have never unlocked still costs 1 credit, because it is your first access to that analysis.

Can I run AI ad analysis on Meta's free Ad Library API data?

Partially. Meta's free API covers political and social-issue ads in most regions (all ad types for EU/UK only) and returns no engagement counts, spend estimates, or analysis, so you would build the transcription and teardown pipeline yourself. The AdLibrary API is the paid alternative: commercial ads across 11 platforms with performance signals and AI enrichment included.

How accurate is AI ad creative analysis?

Strong on transcription, hook classification, and creative structure, weaker on audience inference (it guesses from creative cues, not delivery data), irony-heavy hooks, and chaotic audio. It also cannot tell you whether an ad performed, so pair the analysis with runtime and engagement signals and keep a human review pass before acting on it.

Turn the Screenshot Folder Into a Database

The week-of-watching problem has a precise fix, and AI ad analysis at scale is it. A search call finds the ads the market has already validated. Enrichment extracts the hooks, claims, audiences, and structures from each one as data. The closing LLM pass turns 200 rows into the pattern report your creative team actually argues about on Thursday. The dataset compounds, repeat analysis on known ads is free, and the cost of a full market scan is arithmetic you can do before you run it.

If your team is still trading screenshots, start with the creative-intelligence workflow above on ten ads, then scale. API access ships with the Business plan at €329/month with 1,000+ monthly credits, enough for weekly market scans with room left for ad-hoc teardowns, plus free integration help from the team. Details and key setup live on the API access page, and the in-app version of the same analysis is AI Ad Enrichment if you want to test the output quality on single ads before writing a line of code.

Watching ads one at a time was never the job. Knowing what the market rewards, faster than your competitors learn it, is.