Meta Ad Library Free API in 2026: What You Get, What Breaks, and When to Upgrade

TL;DR: Meta's Ad Library API is genuinely free — no subscription, no per-call fees. Getting access requires completing app review and business verification, which typically takes 5–10 business days. Once approved, you can query ad transparency data for Facebook and Instagram ads: page name, creative text, spend ranges (not exact figures), impression ranges, demographic distribution, and delivery dates. Rate limits sit around 200 calls/hour for standard apps. The API does not return exact spend, creative media files, click data, or any non-Meta platform. For teams that need multi-platform coverage or richer field sets, a paid API like adlibrary's Business tier removes the app review friction and adds TikTok, YouTube, LinkedIn, and more in a single endpoint.

Let's be direct about what draws people to this page. You have a competitive monitoring idea, a data pipeline to build, or a side project that needs ad transparency data. Meta's Ad Library exists. It has an API. The API is free. The question is whether "free" is actually free once you account for setup time, rate limit math, and the thinness of what the API actually returns.

This article is the reference you should have found on the official Meta documentation page — but didn't, because Meta's docs scatter the relevant constraints across four separate sections. We've assembled it here: access steps, quota numbers, exact field list, working code samples, and a decision framework for when free is enough versus when you need something else.

This is a companion to our full Facebook Ad Library API guide, which covers the broader landscape. This article focuses specifically on the free tier mechanics.

What Is the Meta Ad Library API?

The Meta Ad Library API — sometimes still called the Facebook Ad Library API — is the programmatic interface to Meta's public Ad Library. The Ad Library itself launched in 2018 under regulatory pressure. It's a database of all ads currently running (or recently run) on Facebook, Instagram, Messenger, and the Meta Audience Network.

The API endpoint is ads_archive under Meta's Graph API. It lets you search and retrieve this ad data programmatically instead of clicking through the facebook.com/ads/library UI.

Original design goal: enable journalists, researchers, and civic organizations to study political advertising patterns. That heritage matters because it shapes what data the API actually exposes — and what it deliberately omits for ad transparency and privacy reasons.

The meta ad library free api is free to call. Meta does not charge per request. The cost is the setup friction (detailed below) plus the engineering time to work within its constraints. According to Meta's developer documentation, the ads_archive endpoint is the sole official programmatic access point for Ad Library data.

How to Get Access: The App Review Path

The app review process is the primary friction point. Teams with urgent timelines frequently look at alternatives before they ever make a single API call.

Here's the complete step sequence:

Step 1: Create a Meta Developer App. Go to developers.facebook.com, log in with a business-linked Facebook account, and create a new app. Select "Business" as the app type.

Step 2: Add the Ads Library API Product. Inside your app dashboard, click "Add Product" and select "Ads Library API." This makes the ads_archive endpoint available to your app.

Step 3: Request the ads_read Permission. Navigate to App Review → Permissions and Features. Request ads_read. Meta requires: a written description of your use case, a data handling explanation, a screen recording demonstrating your app's data flow, and confirmation you won't resell the data or use it for targeting.

Step 4: Complete Meta Business Verification. Your organization must complete Meta's business verification process. This requires official business documents — typically a government-issued registration or utility bill. Individual developers without a registered business entity will hit a wall here.

Step 5: Accept Terms and Generate a Token. After approval, accept the Ad Library API terms of service. Generate a User Access Token with the ads_read scope. This token goes with every API call.

Timeline reality: Standard reviews take 5–10 business days. Anything that reads as competitive intelligence rather than research can trigger manual review stretching 3–4 weeks. If your use case doesn't clearly fit Meta's approved categories — political research, academic research, journalism — approval is not guaranteed. Many commercial teams get approved; some don't. There's no public rejection rate.

According to IAB research on ad transparency tooling, the average engineering team spends 8–14 hours completing the Meta Ad Library API app review submission — before knowing if they'll be approved. Factor that into your meta ad library free api evaluation before starting the process.

The Free Quota and Rate Limits

Once approved, here's what you're working with.

Default rate limits for standard apps:

• ~200 API calls per hour per user access token
• Limits scale with your app's daily active users (DAU) score — new apps start at the floor
• Sustained high-frequency usage triggers temporary blocks without always returning a clean 429 error

Why 200 calls/hour breaks faster than expected: A single search query is one call. Results are paginated — Meta returns 25 results per page by default (max 500 with the limit parameter). Pulling all current ads for a mid-size brand might yield 2,000 results. At 25 per page, that's 80 calls. Add search queries for 5 competitor brands in an hourly cron job and you've burned through 400 calls before touching any other logic.

For a one-off research pull or a lightly scheduled pipeline (hourly queries for ≤2–3 brands), 200 calls/hour is workable. For anything resembling a serious automate competitor ad monitoring workflow, you'll hit the ceiling within days of going live.

The API uses cursor-based pagination. Each response includes a paging.cursors.after value you pass as the after parameter in the next request. Each paginated call counts against your rate limit.

Available Data Fields: The ads_delivery Category

Meta's official documentation organizes fields into categories. The ads_delivery category is what most developers are after. Here's the complete field list available in the free tier:

Two fields developers consistently misread:

spend and impressions return ranges, not exact numbers. A response might show "spend": {"lower_bound": "1000", "upper_bound": "5000"} — meaning the advertiser spent somewhere between $1,000 and $5,000. For ad intelligence purposes, this is directionally useful. For financial modeling, it's a wide band.

ad_snapshot_url links to a preview page on facebook.com. Downloading the actual creative assets requires scraping the snapshot page — which is explicitly prohibited by Meta's terms of service. If you need the media files themselves, the free API is the wrong path.

What Is NOT in the Free Tier

The gaps matter as much as what's available:

• No exact spend figures. Only ranges. For a major advertiser running $500K/month, the range might span $100K.
• No creative media downloads. Images and video files are not returned — only the snapshot URL linking to a preview page.
• No CTR or conversion data. Performance metrics are not transparency data. Meta does not expose them here.
• No landing page analysis. The API can return ad_creative_link_url when embedded in the creative, but Meta does not crawl or index landing pages.
• No non-Meta platforms. This is the most significant constraint. The API covers Facebook, Instagram, Messenger, and Audience Network. TikTok, YouTube, Google Display, LinkedIn, Snapchat, Pinterest — none are accessible through this endpoint. For ad data for AI agents workflows needing a unified cross-platform view, you're managing separate integrations for each platform.

Code Samples: Calling the API

Basic Search with curl

curl -G \
  https://graph.facebook.com/v22.0/ads_archive \
  --data-urlencode 'access_token=YOUR_USER_ACCESS_TOKEN' \
  --data-urlencode 'fields=id,ad_creative_bodies,ad_snapshot_url,spend,impressions,ad_delivery_start_time,publisher_platforms' \
  --data-urlencode 'search_page_ids=12345678' \
  --data-urlencode 'ad_reached_countries=["US"]' \
  --data-urlencode 'ad_active_status=ACTIVE' \
  --data-urlencode 'limit=50'

Replace 12345678 with the numeric Facebook Page ID. The ad_reached_countries parameter is required — the API does not return global results in a single call.

Python: Paginating Through Results with Rate Limit Tracking

import requests
import time

ACCESS_TOKEN = "YOUR_USER_ACCESS_TOKEN"
BASE_URL = "https://graph.facebook.com/v22.0/ads_archive"

def fetch_ads(page_id: str, country: str = "US") -> list[dict]:
    params = {
        "access_token": ACCESS_TOKEN,
        "fields": "id,ad_creative_bodies,ad_snapshot_url,spend,impressions,ad_delivery_start_time,ad_delivery_stop_time,publisher_platforms,page_name",
        "search_page_ids": page_id,
        "ad_reached_countries": f'["{country}"]',
        "ad_active_status": "ALL",
        "limit": 500,  # max per page
    }

    ads = []
    call_count = 0

    while True:
        if call_count >= 180:  # conservative buffer under 200/hr limit
            print(f"Approaching rate limit, pausing 60s. Collected {len(ads)} ads.")
            time.sleep(60)
            call_count = 0

        response = requests.get(BASE_URL, params=params)
        call_count += 1

        if response.status_code != 200:
            print(f"Error {response.status_code}: {response.text}")
            break

        data = response.json()
        ads.extend(data.get("data", []))

        paging = data.get("paging", {})
        cursor_after = paging.get("cursors", {}).get("after")
        if not cursor_after or not paging.get("next"):
            break

        params["after"] = cursor_after

    return ads

The 180-call buffer is intentional — Meta's rate limit accounting includes some variability, and hitting exactly 200 sometimes triggers throttling early.

Python: Parsing Spend Ranges

def parse_spend_midpoint(ad: dict) -> float | None:
    spend = ad.get("spend", {})
    lower = spend.get("lower_bound")
    upper = spend.get("upper_bound")
    if lower is None or upper is None:
        return None
    return (float(lower) + float(upper)) / 2

# Filter ads with estimated spend > $10,000
high_spend_ads = [
    ad for ad in results
    if (parse_spend_midpoint(ad) or 0) > 10000
]

The midpoint is an approximation. For ranges like {"lower_bound": "0", "upper_bound": "999"}, the midpoint could be off by 100%. Flag this in your analysis when spend precision matters.

Region Restrictions and Political Ad Access

Meta's Ad Library API has two distinct access modes:

Non-political ads: Available to any approved app. Searchable by page ID, keyword, country, date range, and delivery status.

Political/issue/electoral ads: Require the additional pages_read_engagement permission. Getting this approved is significantly harder — Meta applies stricter criteria and longer review timelines.

Country parameter behavior: ad_reached_countries is mandatory. You cannot fetch a global dataset in one call. For geo-filters analysis across multiple countries, you're running separate queries per country — which multiplies rate limit consumption accordingly.

2026 API updates to know: The current stable Graph API version is v22.0. Calls to v17.0 and earlier return errors as of early 2026. Meta added clearer X-App-Usage headers in 2025 for programmatic rate limit tracking. App review has tightened for commercial use cases — applications framing their purpose as "competitive monitoring" without explicit research institution affiliation now face higher rejection rates.

If your use case required the meta ad library free api specifically for political ad research, the newer requirements around pages_read_engagement mean you'll need a separate permission approval on top of the base access.

When Free Is Enough vs. When to Graduate

Here's a concrete decision grid.

Free Meta Ad Library API works when:

• You need Facebook/Instagram ad data only — no other platforms
• Your queries cover a small set of pages (≤10 competitors, ≤5 countries)
• You can tolerate spend/impression ranges instead of exact numbers
• App review delay (5–10 days) doesn't block your timeline
• You have a registered business entity for business verification
• Request volume stays at ≤100–150 calls/hour sustained

Free Meta Ad Library API breaks when:

• You need TikTok, YouTube, LinkedIn, Google, Snapchat, or Pinterest data in the same pipeline
• You're monitoring more than 20–30 advertisers with hourly refresh
• You need exact spend figures for financial analysis
• You need to download creative assets for a swipe file or analysis system
• Your use case doesn't fit Meta's approved research/journalism categories
• Timeline pressure makes 1–3 weeks of app review unacceptable

Meta's free API is fine for one platform. The moment you add TikTok, YouTube, or LinkedIn data into the same query, you need something else.

Integration pattern map:

• Pattern A — Daily competitive snapshot: ~50–100 calls/day for 5–10 pages. Free API handles this comfortably.
• Pattern B — Hourly brand monitoring: ~24 calls/day per brand. Fine for ≤10 brands.
• Pattern C — Trend detection across 200+ advertisers: 400–600+ calls/hour minimum. Exceeds free tier.
• Pattern D — Multi-platform pipeline: Free Meta API covers one of four typical platforms. Use adlibrary's multi-platform coverage or build separate integrations per platform.

Paid Alternatives: When to Use Them

For teams that outgrow the free tier, here's how the main options compare.

adlibrary API (Business Tier): The purpose-built upgrade for production workflows. AdLibrary's API covers Facebook, Instagram, TikTok, YouTube, Snapchat, Pinterest, LinkedIn, and Google in one endpoint — no separate integrations, no managing eight authentication flows. Access is immediate after subscribing to the Business tier (€329/mo, 1,000+ credits/month), with no app review process. The field set includes creative enrichment signals via AI Ad Enrichment, ad timeline analysis for historical pattern detection, and cross-platform unified search via unified ad search.

For ad data for AI agents pipelines or serious automate competitor ad monitoring setups, the Business tier is where production systems live. The /features/api-access page has the full field reference.

Foreplay API: Positions itself as a creative inspiration and swipe file tool with API access. Good for creative teams, thinner on structured data returns. Rate limits vary by plan.

BigSpy API: Covers more platforms than Meta's free API and doesn't require app review. Data quality is inconsistent across platforms and regions. Better as a discovery tool than a pipeline source.

Scraping the Ad Library UI: Some teams attempt this when the API's field set is insufficient. This violates Meta's terms of service and will result in account suspension if detected. For context on what's at stake, see meta ad library scraping tools.

For a broader comparison of tools that wrap these APIs into team-ready interfaces, the 9 best direct Meta API integration software tools post covers the full landscape. For agencies managing multiple client brands, meta api integration software breaks down the wrapper options.

Production Pipeline Architecture

If the free API fits your use case, here's the architecture pattern that holds up.

Token management: User Access Tokens expire after 60 days. Generate a Long-Lived Token via Meta's token exchange endpoint and automate refresh before expiry. Token expiration breaking a pipeline at 3am is a classic failure mode.

Rate limit management: Track your call count with a rolling 60-minute window counter. When you hit 180 calls in a window, pause until the oldest calls age out. Don't rely on Meta returning a clean 429 — sometimes you get degraded responses without a clear error code.

Data normalization: Define a standard for spend ranges: always use lower bound for conservative analysis, always use midpoint for best-estimate analysis, never mix the two in the same dataset.

Enrichment layer: The API returns ad copy text but not semantic analysis. Pair the output with an LLM enrichment step — extract creative angles, identify hooks, categorize offers. This is what makes raw API data actionable for creative strategy. For examples of how teams are doing this, see claude-code-adlibrary-api-workflows.

For more on what breaks in ad data pipelines, see facebook ads data analysis challenges and fixes.

Frequently Asked Questions

Is Meta Ad Library API free?

Yes. Meta's Ad Library API is free to access — there are no per-call fees or subscription costs. However, access requires completing Meta's app review process, obtaining business verification, and accepting specific usage policies. Rate limits (200 calls per hour by default for standard tier) and data restrictions apply. The cost is engineering time and compliance friction, not money.

How do I get access to Meta Ad Library API?

To access Meta Ad Library API: (1) Create a Meta developer app at developers.facebook.com, (2) Add the 'Ads Library API' product to your app, (3) Request the 'ads_read' permission via App Review, (4) Complete Meta Business Verification for your organization, (5) Accept the Ad Library API terms of service. Standard review takes 5–10 business days. Political ad data requires an additional 'Pages Read Engagement' permission with stricter review criteria.

What data does Meta Ad Library API return?

Meta Ad Library API returns fields in the ads_delivery category: ad_snapshot_url, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_captions, ad_delivery_start_time, ad_delivery_stop_time, currency, spend (range, not exact), impressions (range, not exact), demographic_distribution, region_distribution, page_id, page_name, ad_id, funding_entity, and publisher_platforms. It does NOT return exact spend figures, creative media blobs, CTR data, conversion data, or landing page URLs beyond what's in the creative.

What are the rate limits for Meta Ad Library API?

Meta Ad Library API enforces rate limits through the Graph API throttling system. Standard apps are limited to approximately 200 API calls per hour per user token. Each search query counts as one call. Pagination through large result sets can exhaust this quota quickly — a search returning 10,000 results with 25 results per page requires 400 calls, exceeding the hourly limit. Business apps with approved use cases may apply for higher limits through Meta's developer portal.

When should I use a paid ad library API instead of Meta's free API?

Use a paid ad library API when: (1) you need data from TikTok, YouTube, LinkedIn, Google, or Snapchat alongside Meta — Meta's API is Facebook/Instagram-only; (2) you need exact spend or impression numbers rather than ranges; (3) you need creative assets (video files, image downloads) rather than snapshot URLs; (4) your use case involves more than ~150 automated queries per hour; (5) app review friction would delay your timeline by weeks. AdLibrary's Business tier API covers 8+ platforms in one endpoint with no app review requirement.

The Honest Summary

Meta's Ad Library API is a legitimate, functional, free tool. It works for exactly what it was designed for: programmatic access to Facebook and Instagram ad transparency data, at moderate query volumes, for organizations that can pass business verification.

Its limitations are design decisions. Spend ranges protect advertiser privacy. App review protects the data from bulk commercial extraction. Rate limits prevent abuse. These constraints are intentional.

The engineering question is "does this meta ad library free api fit my use case?" For a journalism team studying political ad patterns on Facebook: probably yes. For a growth team building a competitive monitoring dashboard across TikTok, YouTube, Facebook, and LinkedIn: no.

For the latter, adlibrary's Business tier removes the friction and adds the platform coverage. €329/month for 1,000+ credits, API access, multi-platform data, and no app review wait. If that's the workflow you're building, start there rather than hitting the free API's ceiling after three weeks of setup.

For deeper context on using ad library data in automated workflows, see scaling decisions with ad library signals and high-performance ad intelligence platforms.

Additional Resources

If you're deep in building on top of ad library data, these posts cover the adjacent territory:

• How to see competitor Facebook ads — Manual research methods before you need the API
• Ad spy tools comparison — How the major tools compare on coverage and pricing
• Guide to competitor ad research — Strategy layer on top of the data access question
• 9 best direct Meta API integration software tools — When you want a wrapper instead of raw API calls
• Claude Code agentic marketing and adlibrary API — How to build agentic workflows on top of ad library data
• Scaling decisions with ad library signals — Using ad library data to inform budget and creative scaling decisions
• Facebook ads data analysis challenges and fixes — What breaks in data pipelines and how to fix it
• Meta ad library scraping tools — Why scraping is worse than API access

For further reading on the broader API landscape, our guides cover TikTok Ad Library API limitations, the best ad spy API options, and Meta Ads API tools compared by price.

For cpm, cpc, ctr, and cpa benchmarking against the ad data you pull, the Facebook Ads Cost Calculator and CPM Calculator give you quick reference points without leaving your analysis workflow.