What Is an Ad Library API? How Programmatic Ad Transparency Works

Every major ad platform now maintains a public archive of the ads it serves. An ad library API is the layer that makes those archives programmable: you send a query, you get structured JSON back, and your scripts do the reading instead of your eyeballs.

TL;DR: Ad libraries began as compliance projects after the 2018 political-ad backlash. Today they hold the richest competitive dataset in advertising, and an ad library API is how you query that dataset instead of scrolling it. Meta's free API covers political and social-issue ads (plus EU and UK ads) on Meta properties only. Commercial options such as the AdLibrary API return commercial ads across 11 platforms and attach performance signals like spend estimates, runtime, and heat scores. This guide covers where ad libraries came from, what an API layer adds, what data each ad carries, and a first query you can run in five minutes.

If you have ever built a competitor deck by screenshotting the Facebook Ad Library tab by tab, you already understand the problem this solves. The archive is public. The access model is the bottleneck.

What Is an Ad Library? The Transparency Layer Behind Every Platform

An ad library is a public, searchable archive of the advertisements running on a platform. Anyone can open one in a browser, type a brand name, and see what that brand is paying to show people. No login, no ad account, no spend required.

Meta started it. After the Cambridge Analytica scandal and the scrutiny that followed the 2016 US election, Meta launched a searchable archive of political ads in 2018, then expanded it into the full Ad Library covering every active ad on Facebook and Instagram. What began as a regulatory peace offering quietly became the largest free dataset of live advertising creative ever published.

Regulators then made the pattern mandatory. The EU's Digital Services Act requires very large online platforms to maintain public ad repositories, which is why 2023 and 2024 produced a wave of new libraries. Google shipped its Ads Transparency Center in 2023. TikTok opened its Commercial Content Library, and LinkedIn followed with an Ad Library of its own. Each platform now delivers some version of the same promise: the ads are public record.

For marketers, the compliance origin story is a footnote. The practical consequence is the headline. Every competitor's live creative, copy, and landing-page strategy sits in a public archive, refreshed continuously. Ad transparency rules built the dataset. Competitive researchers inherited it. Our guide to transparency libraries and regulatory standards covers the legal side in depth, and the Meta Ad Transparency Center walkthrough shows what the browsing experience looks like today.

What an Ad Library API Adds: From Browsing to Querying

The browser interfaces share one limitation. They are built for a human looking at one thing, and competitive research is rarely about one thing.

Manual research against a web ad library looks like this: open the page, search a brand, scroll, screenshot, paste into a doc. Repeat for the next brand, the next platform, the next client. A ten-competitor sweep across four platforms means forty separate browsing sessions, and the results are stale the moment you finish.

An ad library API replaces that loop with a request. Programmatic access means the archive becomes a database you query: filter by keyword, brand, country, format, or date range, and receive structured data your code can act on. The shift sounds small. It changes everything downstream, because JSON flows into places screenshots cannot:

• Scheduled monitoring. A cron job pulls last night's new competitor ads at 6am, every day, without anyone opening a browser. See the competitor ad monitoring workflow for a concrete setup.
• AI pipelines. Agents and scripts consume ad data directly. Ad data for AI agents is now one of the fastest-growing reasons teams want programmatic access at all.
• Internal dashboards. Share-of-voice trackers, creative-velocity charts, and client reporting that update themselves.
• Bulk analysis. A thousand ads scored against your own criteria in minutes, instead of forty browser tabs scored by gut feel.

This is the core of ad intelligence as a practice: turning the public record of advertising into a feed your systems can reason over. Browsing answers "what does this one brand run?" Querying answers "what is working in this entire market, ranked?"

The Public Ad Library APIs, Platform by Platform

Not every transparency archive has an API, and the ones that exist differ sharply in scope. Here is the honest map as of 2026.

Meta Ad Library API

Meta's is the original and still the most cited. The Ad Library API is free and runs through the Graph API's ads_archive endpoint. Before you call it, you confirm your identity and location, register as a developer on developers.facebook.com, and generate an access token that expires every 60 days unless you build a refresh flow.

The catch sits in the coverage. Globally, the API returns political and social-issue ads. Commercial ads are queryable only for the EU and UK, where the DSA forces broader disclosure, and only for the last 12 months. A US DTC brand's product ads are visible in the browser interface yet largely absent from the free API. Our Meta Ad Library free API breakdown walks through exactly what you get and where it stops.

A minimal query looks like this:

curl -G "https://graph.facebook.com/v23.0/ads_archive" \
  --data-urlencode "search_terms=protein powder" \
  --data-urlencode "ad_reached_countries=['DE']" \
  --data-urlencode "fields=page_name,ad_creative_bodies,ad_delivery_start_time" \
  --data-urlencode "access_token=YOUR_TOKEN"

Google Ads Transparency Center

Google's Ads Transparency Center covers ads across Google Search, YouTube, and Display, but it ships without a general public API. Political ad data is published as downloadable transparency reports. For commercial YouTube and Search ads, you browse, or you go third-party. The YouTube ads alternative guide covers what the Transparency Center will and will not show you.

TikTok and LinkedIn

TikTok's Commercial Content Library includes a research API, though access requires an application and targets academic and public-interest research rather than marketing teams. LinkedIn's Ad Library is browser-only, with no public API at all. The respective deep dives, the TikTok Ad Library guide and LinkedIn Ad Library 2026, map the gaps in detail.

The pattern across all four: transparency archives exist everywhere, programmatic access is the exception, and commercial ad data through official channels is thin outside the EU.

Public vs Commercial Ad Library APIs

That gap is the entire reason commercial ad library APIs exist. They are paid products that aggregate ad data across platforms and sell programmatic access with research features layered on top.

The AdLibrary API is the one we build, so the comparison below is the honest version of our own pitch. Meta's API is free and ours is not. If political ads on Facebook are genuinely all you need, use Meta's and save your money.

Three differences carry most of the weight in practice:

1. More data per ad. Public APIs return what regulation requires. A commercial ad library API adds the research layer: engagement counts, impression signals, estimated spend, and a heat score that says whether a creative is scaling right now.
2. Multi-platform in one call. Meta's free API is fine for one platform. The moment your research spans TikTok, YouTube, or LinkedIn in the same query, you need something else. One request against multi-platform coverage replaces eleven separate integrations.
3. Simpler to implement. One key, one header, no app review, no identity verification, no token babysitting. Teams that have fought Meta's review queue know why API access without the wait became its own search category.

If you are weighing the free option seriously first, Is Meta Ad Library enough, or should you pay? is the longer decision framework. And if your current plan is "we'll just scrape it," read the scraping tools reality check before you commit. Scraping Meta violates their terms and breaks every time the markup shifts.

What Data Comes Back Per Ad

The unit of an ad library API is the ad object. Here is a representative result from the AdLibrary /api/search endpoint:

{
  "results": [
    {
      "ad_key": "fb_123456789",
      "advertiser_name": "Acme Running",
      "platform": "facebook",
      "title": "The shoe that runs with you",
      "body": "Lightweight. Responsive. Built for race day.",
      "button_text": "Shop Now",
      "ads_type": 2,
      "impression": 1840000,
      "heat": 812,
      "like_count": 9420,
      "share_count": 1180,
      "first_seen": 1748390400,
      "days_count": 89,
      "geo": ["US", "GB", "DE"],
      "preview_img_url": "https://...",
      "video_url": "https://...",
      "landing_page_url": "https://acme.example/run"
    }
  ],
  "total": 327,
  "page": 1,
  "_credits": { "used": 1, "remaining": 4999 }
}

Grouped by what each field is for:

• Identity. ad_key is the stable identifier across calls, while advertiser_name and platform tell you who and where. Dedupe and store on ad_key.
• Creative and copy. Title, body, caption, and button_text give you the full text layer. The ad creative itself arrives as direct image and video URLs, with ads_type flagging image, video, carousel, or collection.
• Performance signals. impression is reach, heat is a 0 to 1000 momentum score, and the engagement counts capture social traction. Two caveats belong in every pipeline you build: platform-sourced impression figures are bucketed ranges rather than exact counts, and spend is always an estimate, never a number the advertiser reported. Treat both as bands. To sanity-check an estimate against benchmark math, run the ad spend estimator in reverse from impressions and CPM.
• Time and place. first_seen and days_count establish runtime, and geo lists the countries where the ad is running.

Runtime deserves a special mention. days_count is the single most reliable proxy for "this ad converts," because advertisers kill losing creatives within days and keep feeding winners. An ad at day 89 has survived 89 days of someone's budget reviews.

Who Uses an Ad Library API

Three groups account for most ad library API usage, and they want different things from the same dataset.

Media buyers and growth marketers use it as a research feed. Instead of opening five ad libraries before a creative sprint, they pull the longest-running and highest-heat ads in their niche into a sheet or notebook, then mine the hooks. The classic ad spy workflow, minus the manual collection. Many wire it into alerting too, so a competitor scaling a new concept triggers a Slack message rather than a quarterly surprise. The competitor ad monitoring guide shows that setup end to end.

Agencies run an ad library API across a client roster. One integration produces competitor research and creative briefs for every account, on a schedule, with data fresh the day the deck ships. Low-code stacks are common here, and the n8n recipes cover scheduled pulls and enrichment without writing a server.

Developers and SaaS builders treat it as infrastructure. Anyone building competitive intelligence features into their own product faces a choice between stitching together eleven platform integrations or calling one REST API. Some go further and put the API behind their own agent tooling, like the teams running Claude Code workflows against the AdLibrary API or wrapping it in an MCP server so any AI assistant can query ad data natively.

Your First Ad Library API Query

Time to run one. This walkthrough uses the AdLibrary API because it is the fastest path from zero to commercial ad data, and because the auth model is a single header.

Step 1: Create an API key. API access comes with the Business plan. In your dashboard, generate a key. It starts with adl_, it is shown to you exactly once, and you can hold up to 10 keys per account to separate clients or environments.

Step 2: Send a search. One POST, one header, one JSON body:

curl "https://adlibrary.com/api/search" \
  -H "Authorization: Bearer adl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "protein powder",
    "appType": "3",
    "platform": ["facebook", "instagram", "tiktok"],
    "adsType": ["2"],
    "sortField": "-impression",
    "daysBack": 30
  }'

That asks for video ads (adsType: ["2"]) mentioning "protein powder" in the e-commerce vertical (appType: "3"), active in the last 30 days, sorted by impressions, across three platforms at once. Every parameter except appType is optional, and the filter surface goes deep: country, language, aspect ratio, video length, call-to-action category, engagement ranges, even e-commerce platform, so you can study only Shopify stores if that matches your stack.

Step 3: Read the response. You get the JSON shape from the previous section: a results array of ad objects, a total count of everything that matched, and a _credits block showing what the call cost and what remains.

The same call in Python:

import requests

r = requests.post(
    "https://adlibrary.com/api/search",
    headers={"Authorization": "Bearer adl_your_api_key"},
    json={
        "keyword": "protein powder",
        "appType": "3",
        "sortField": "-days",
        "daysBack": 90,
    },
)
data = r.json()
print(f"{data['total']} ads, {data['_credits']['remaining']} credits left")

for ad in data["results"][:10]:
    print(ad["days_count"], ad["advertiser_name"], ad.get("title", ""))

Note the sort change. -days surfaces the longest-running creatives, the proven survivors, where -impression surfaces raw reach. Different question, one parameter.

No app review happened in any of those steps. No identity documents, no 60-day token countdown. That is the implementation gap between transparency-built APIs and research-built ones, and the full endpoint documentation covers everything beyond this first call.

Reading the Response: The Signals That Matter

A first ad library API query returns 60 ads per page by default, and pageSize goes up to 100. The skill is knowing which fields drive decisions.

Use total for market sizing. The search response includes a total count of matching ads, which makes keyword-level sizing a one-call job. 327 active video ads for "protein powder" tells you something about category saturation before you read a single creative.

Sort by signal, not date. -heat_degree and -impression surface what is scaling now. -days surfaces what has earned its budget over months. A creative team planning next quarter's concepts wants the second list more than the first.

Escalate selectively to enrichment. Once a handful of ads clear your heat or runtime threshold, the /api/enrichment endpoint runs a full AI teardown of a single ad: timestamped transcript, hook analysis, persuasion structure, and a 1:1 replication creative brief formatted for AI image and video tools. The AI ad enrichment feature is the second half of the loop the API exists for. Find the proven angle, get the brief, rebuild it with your own product.

Resolve brands before you track them. The free /api/advertisers/search endpoint matches a brand name across Meta, Google, and LinkedIn in one call. Save the advertiser, and the curate endpoint then pulls its recent ads across accounts and platforms in one request, deduped. One brand is rarely one account, so this matters more than it sounds (Nike alone runs Nike, Nike Football, Nike Run Club, and more).

Let the API score portfolios for you. The winners endpoints scan an advertiser's whole portfolio and return the concepts that brand has demonstrably scaled, with plain-language evidence like "runtime 89 days, top 10% of this advertiser." That is the "which of their ads actually work" question answered as data.

What an Ad Library API Costs

Meta's Ad Library API is free, full stop. Your costs there are engineering time: the review process, the token refresh flow, the rate-limit management, and the workarounds for everything the API does not return. Free has a real price when the dataset ends where your research starts. Exporting around those limits is its own genre of workaround, as the Meta export guide shows.

Commercial ad library APIs are typically usage-priced. AdLibrary uses credits:

• Search: 1 credit per page of results. A failed search refunds its credit automatically.
• AI enrichment: 1 credit per ad analysis (text ads and videos up to 180 seconds).
• Advertiser tracking: brand resolution is free, and curating a saved advertiser costs 1 credit per 30-minute session regardless of how many pages you pull inside it.
• Winners scan: 10 credits flat for a full portfolio scoring, auto-refunded if the scan comes back empty or errors.

API access itself lives on the Business plan at €329/mo with 1000+ monthly credits, free integration help, and prioritized feature requests. For a team currently spending a researcher's afternoon per competitor sweep, the math resolves quickly. Put a number on what those hours return today with the ROAS calculator, then look at the pricing page with your monthly research volume in mind. If you want to inspect the data before automating anything, the cheaper plans let you run real searches in the app first and upgrade once the workflow is proven.

Common Mistakes When You Start Querying Ad Data

Every team that adopts an ad library API makes a subset of these. Skip the full set:

1. Treating impressions as exact. They are bucketed ranges on the platform side. Build your scoring on bands and relative comparisons, never on false precision.
2. Quoting spend estimates as actuals. Estimated spend is modeled. Useful for ranking who spends more, wrong for invoicing-grade claims in a client deck.
3. Ignoring rate limits. The AdLibrary API allows 10 requests per minute and 10,000 per day per key, and a 429 response carries a Retry-After header. Honor it. A polite client outruns a hammering one over any real workload.
4. Re-querying instead of caching. ad_key is stable across calls. Store results, dedupe on the key, and query for deltas. Identical repeat searches cost real credits and return what you already had.
5. Enriching everything. Run AI teardowns on the ads that clear your runtime or heat threshold, the shortlist rather than the firehose. Credit budgets die from indiscriminate enrichment.
6. Scraping instead. Scraping violates platform terms, breaks on every markup change, and produces a maintenance treadmill. The ad spy tools comparison shows how supported APIs stack up against scraper-based tooling on reliability alone.

Frequently Asked Questions

What is an ad library API?

An ad library API is a programmatic interface to a public archive of advertisements. Instead of browsing ads in a web interface, you query them with code and receive structured JSON containing creative, copy, advertiser identity, and, on commercial APIs, performance signals like impressions, spend estimates, and runtime.

Is Meta's Ad Library API free?

Yes. Meta's Ad Library API is free, but it requires identity verification and app review, its tokens expire every 60 days, and it returns political and social-issue ads globally with commercial ads limited to the EU and UK for the last 12 months. Commercial APIs charge for broader coverage and richer data.

What data does an ad library API return for each ad?

A typical ad object includes the creative URLs (image or video), title, body and call-to-action text, advertiser name, platform, format, geo, and timing fields like first-seen date and runtime. Commercial APIs add engagement counts, bucketed impressions, estimated spend, and trend signals such as a 0 to 1000 heat score.

Do I need to scrape the Facebook Ad Library if I use an ad library API?

No, and you should not scrape it regardless. Scraping violates Meta's terms and breaks whenever the page markup changes. Meta's official API covers political and EU/UK ads for free, and commercial ad library APIs provide supported, stable access to multi-platform commercial ad data.

How much does a commercial ad library API cost?

Most are usage-priced. The AdLibrary API is included in the Business plan at €329/mo with 1000+ monthly credits, where a search costs 1 credit per page and an AI creative analysis costs 1 credit. Failed calls refund automatically, and brand resolution across platforms is free.

Stop Browsing, Start Querying

The transparency era handed marketers a strange gift: every competitor's advertising, published in public, updated continuously. Most teams still read that archive one browser tab at a time.

An ad library API is the difference between visiting the data and operating on it. Meta's free API is the right starting point if political ads or EU-region Meta research covers your needs, and you should know its edges before paying for anything. The moment your questions span platforms, need performance signals, or belong inside a script, an agent, or a nightly job, the commercial route stops being a luxury.

Start small. Get API access on the Business plan, run the protein-powder query from this guide against your own market, and sort by -days. The list of ads that survived 90 days of someone else's budget reviews is the cheapest creative-strategy document you will read this quarter.