Facebook Ad Library API: What It Actually Gives You (And What It Doesn't)

What Is the Facebook Ad Library API?

The Facebook Ad Library API is a REST endpoint provided by Meta as part of the Graph API. It allows developers to programmatically query ad transparency data from the Facebook Ad Library, which was launched in 2019 for political ad transparency. The endpoint is https://graph.facebook.com/v24.0/ads_archive.

According to Meta's documentation, the Ad Library API provides access to data about ads related to social issues, elections, and politics. While a broader ad_type=ALL parameter exists, its coverage for commercial ads is widely reported as incomplete. The API requires a Facebook App ID, user access token, and in some cases identity verification.

For developers searching for a facebook ad library api tutorial or trying to understand meta ad library api documentation, this guide covers everything you need to know—including the limitations that official docs don't make obvious.

Quick Facts

How to Set Up the Facebook Ad Library API (Step-by-Step)

Setting up the Facebook Ad Library API requires creating a Meta app, obtaining and managing access tokens, and writing pagination logic. Here's the complete process for how to use facebook ad library api in your projects.

Step 1: Create a Meta App

Go to developers.facebook.com and create a new app. Select the Business type. This gives you an App ID, which is required for all API calls. You'll also need to add the Marketing API product to your app.

For political ad data, Meta requires additional identity verification. This process can take several days and requires a government-issued ID matching your developer account country.

Step 2: Get Your Access Token

In the Graph API Explorer, select your app and request the ads_read permission. Generate a short-lived user access token, then exchange it for a long-lived token:

curl -X GET "https://graph.facebook.com/v24.0/oauth/access_token \
  ?grant_type=fb_exchange_token \
  &client_id=YOUR_APP_ID \
  &client_secret=YOUR_APP_SECRET \
  &fb_exchange_token=SHORT_LIVED_TOKEN"

Important: Long-lived tokens expire after 60 days. You'll need to build token rotation logic or manually refresh them. This is one of the most common pain points—if your token expires and you don't notice, your entire data pipeline goes silent.

Step 3: Make Your First API Call

Here's a basic cURL request to search for ads:

curl -X GET "https://graph.facebook.com/v24.0/ads_archive \
  ?access_token=YOUR_TOKEN \
  &ad_type=ALL \
  &search_terms=nike \
  &ad_reached_countries=['US'] \
  &fields=ad_creative_body,page_name,ad_snapshot_url,ad_delivery_start_time \
  &limit=25"

And the equivalent Python code:

import requests

params = {
    'access_token': 'YOUR_TOKEN',
    'ad_type': 'ALL',
    'search_terms': 'nike',
    'ad_reached_countries': "['US']",
    'fields': 'ad_creative_body,page_name,ad_snapshot_url,ad_delivery_start_time',
    'limit': 25
}

response = requests.get(
    'https://graph.facebook.com/v24.0/ads_archive',
    params=params
)
data = response.json()

Step 4: Handle Pagination

The API returns 25 results per page by default. To get more, you need to follow cursor-based pagination using the after parameter:

import requests

def get_all_ads(search_terms, token, country='US'):
    all_ads = []
    url = 'https://graph.facebook.com/v24.0/ads_archive'
    params = {
        'access_token': token,
        'ad_type': 'ALL',
        'search_terms': search_terms,
        'ad_reached_countries': f"['{country}']",
        'fields': 'ad_creative_body,page_name,ad_snapshot_url',
        'limit': 25
    }

    while True:
        response = requests.get(url, params=params)
        data = response.json()

        if 'data' not in data:
            break

        all_ads.extend(data['data'])

        # Check for next page
        paging = data.get('paging', {})
        if 'next' not in paging:
            break

        url = paging['next']
        params = {}  # URL already contains params

    return all_ads

Note that pagination can become unreliable for large datasets. Users report the API returning empty pages or stopping unexpectedly well before all results are returned.

What Data Does the Facebook Ad Library API Return?

The Facebook Ad Library API returns a set of fields for each ad record. Understanding which fields are available—and which are conspicuously absent—is critical before building a data pipeline around this API.

Available Fields (Complete List)

What's Missing: Data the API Doesn't Provide

There are significant gaps in what the Facebook Ad Library API returns. These missing data points are often the most valuable for competitive intelligence and ad research:

• Creative images and videos — Only ad_snapshot_url (an HTML page link), not actual media files
• Engagement data — No likes, comments, shares, or reactions
• Performance metrics — No clicks, conversions, or CTR data
• Targeting data — No audience targeting info (except limited EU DSA data)
• Landing page URLs — Not consistently returned
• Historical/archived ads — Only current Ad Library state, no archive of removed ads

As noted by Swipekit: "The Ad Library's API won't return information such as ad assets, advertiser info, etc. That can be fetched via scraping."

7 Critical Limitations of the Facebook Ad Library API

Understanding the facebook ad library api limitations is essential before committing to building around it. These aren't edge cases—they're fundamental constraints that affect most production use cases.

1. Commercial Ads Data Is Severely Limited

The API was built for political ad transparency. When querying commercial ads with ad_type=ALL, the results are often incomplete or empty. This is the single biggest limitation for business users.

Meta's own documentation confirms: "Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics." For meta ad library api commercial ads, this is a dealbreaker.

2. No Direct Access to Creative Assets

The API returns ad_snapshot_url—a link to an HTML snapshot page. It does not provide direct URLs to images, videos, or carousel creative assets. To get actual media files, you need to build a separate scraper for the snapshot pages, adding significant complexity to your pipeline.

For teams doing creative research or competitive analysis, the inability to programmatically access meta ad library api images and videos makes the official API impractical without additional infrastructure.

3. Access Tokens Expire Every 60 Days

Long-lived tokens have a 60-day expiration. This means you need to either manually refresh your token every two months or build an automated token rotation system. If the token expires unnoticed, your data pipeline stops silently.

This is a common source of frustration documented across developer forums. Many teams discover the facebook ad library api access token expires issue only after their production pipeline has been down for hours or days.

4. Undocumented Rate Limits

Rate limiting is the mechanism that controls how many API requests you can make in a given time period. For the Facebook Ad Library API, the rate limits are not clearly documented by Meta.

The object_count_pct header is supposed to indicate remaining capacity, but there's no documentation on what the values mean, how fast they recover, or what the actual facebook ads library api rate limit thresholds are. Marketing API limits (5,000 calls for Dev tier, 190,000 for Standard) may apply, but Meta hasn't confirmed this for the Ad Library endpoint.

5. Incomplete Results for Many Pages

Users consistently report that the facebook ad library api not showing all ads. Pages with dozens or hundreds of visible ads in the browser may return zero or partial results through the API.

6. Maximum 50,000 Results Per Query

The Ad Creative endpoint caps at 50,000 results—pagination beyond that point stops working. For large-scale data collection (e.g., all ads in a country or industry), this facebook ad library api maximum results cap is a hard wall. There is no workaround documented by Meta.

7. No Alerting, Webhooks, or Real-time Updates

The API is purely pull-based. There's no way to subscribe to new ads, receive notifications when a competitor launches a campaign, or get real-time alerts. You must build your own polling logic, diffing system, and notification pipeline—adding weeks of development time for what should be a basic feature.

Who Should Use the Official Facebook Ad Library API?

Despite its limitations, the official API is the right choice in certain scenarios. We believe in being honest about this:

• Academic researchers tracking political ads: The API provides solid coverage for political and issue ads. If your research focuses on election transparency, it's the most legally clear data source
• One-off research projects: If you need to pull ad data once for a report and don't need ongoing access, the free API is hard to beat
• Budget is exactly $0: If you have no budget for data tools and are willing to spend 4-8 hours on setup plus ongoing token maintenance, the official API is free
• Political ad monitoring tools: If your product specifically tracks political ads, the official API's focus on this category is actually an advantage

For everyone else—SaaS builders, agencies, competitive intelligence teams, creative researchers—the limitations of the official API create real problems that compound over time.

When You Need More: Metapi as a Complete Alternative

Metapi is a managed API service that provides comprehensive Facebook Ad Library data without the limitations of Meta's official endpoint. Here's what changes when you switch to a meta ad library api alternative built for production use.

All Ad Types, Not Just Political

Metapi returns all ad types: commercial, political, housing, employment, and credit ads. You get the same comprehensive data regardless of ad category. No more empty results for commercial advertisers that clearly have active campaigns.

Creative Assets Included (Images, Video, Carousel)

Every Metapi response includes direct URLs to creative assets—images, videos, and individual carousel cards. No need to build a separate scraper for ad_snapshot_url pages. Download creatives directly or embed them in your application.

No Expiring Tokens — Simple API Key

Metapi uses permanent API keys. No 60-day expiration, no token rotation logic, no silent pipeline failures. Get your key once and use it indefinitely.

Complete Data — 95%+ Coverage

Metapi achieves 95%+ ad coverage through multi-method data extraction and cross-validation. The facebook ad library api incomplete results problem doesn't exist—if an ad is visible in the Ad Library, Metapi captures it.

Built-in Webhooks for New Ad Alerts

Subscribe to new ads, creative changes, or volume spikes via webhooks. Integrate with Slack, email, or any endpoint. No polling, no diffing logic, no custom notification pipeline to build and maintain.

Normalized Data Schema (No Parsing Needed)

Every response follows a consistent, documented JSON schema. Field names, types, and structures are always the same. No surprises, no edge cases, no custom parsing logic for different ad types.

Side-by-Side: Meta Ad Library API vs Metapi

Here's a comprehensive comparison across every dimension that matters for production ad data pipelines.

Migration Guide: From Meta API to Metapi

If you've built around the official Facebook Ad Library API and are hitting its limitations, migrating to Metapi is straightforward. Here are the four steps.

Step 1: Map Your Current API Calls

Document which ads_archive fields you currently request and how you use them. Metapi covers all standard Ad Library fields plus additional data (creative URLs, historical archive, engagement indicators). Create a field mapping table between Meta's schema and Metapi's normalized schema.

Step 2: Replace Endpoints

Swap the Meta Graph API endpoint for the Metapi endpoint. Replace your access token with your Metapi API key. The query parameters are similar—search terms, country codes, advertiser IDs, and date ranges—so the migration is mostly mechanical.

Step 3: Remove Token Management Code

Delete your token refresh logic, expiration monitoring, and rotation code. With Metapi's permanent API keys, this entire subsystem becomes unnecessary. This is typically 50-200 lines of code you can safely remove.

Step 4: Add Webhook Listeners (Optional)

If you've built polling logic to detect new ads, you can replace it with Metapi webhooks. Set up an endpoint in your app to receive webhook payloads, and configure your alert preferences in the Metapi dashboard. This eliminates scheduled jobs, diffing logic, and notification code.

Code Comparison: Same Task, Both APIs

Here's a real-world comparison: fetching all active ads for a specific advertiser. Notice the difference in complexity, error handling, and lines of code.

Meta Ad Library API (Python)

import requests
import time

def get_ads_meta_api(page_id, token):
    """Fetch all ads for a page using Meta's official API."""
    all_ads = []
    url = 'https://graph.facebook.com/v24.0/ads_archive'
    params = {
        'access_token': token,  # Expires in 60 days!
        'ad_type': 'ALL',
        'search_page_ids': page_id,
        'ad_reached_countries': "['US']",
        'fields': ','.join([
            'ad_archive_id', 'ad_creative_body',
            'page_name', 'ad_snapshot_url',
            'ad_delivery_start_time',
            'ad_delivery_stop_time',
            'publisher_platforms'
        ]),
        'limit': 25  # Max ~500 per page
    }

    while True:
        try:
            response = requests.get(url, params=params)
            response.raise_for_status()
        except requests.exceptions.HTTPError as e:
            if response.status_code == 429:
                time.sleep(300)  # Rate limited - wait 5 min
                continue
            raise

        data = response.json()

        if 'error' in data:
            raise Exception(f"API Error: {data['error']}")

        if 'data' not in data:
            break

        all_ads.extend(data['data'])

        paging = data.get('paging', {})
        if 'next' not in paging:
            break

        url = paging['next']
        params = {}

    # NOTE: No creative images/videos returned
    # NOTE: Commercial ads may be missing
    # NOTE: Token may have expired silently
    return all_ads

Metapi (Python)

import requests

def get_ads_metapi(page_id, api_key):
    """Fetch all ads for a page using Metapi."""
    response = requests.get(
        'https://api.metapi.io/v1/ads',
        headers={'Authorization': f'Bearer {api_key}'},
        params={'page_id': page_id, 'country': 'US'}
    )
    return response.json()['data']
    # Includes: creative URLs, all ad types, complete data

The Meta API version requires ~35 lines with pagination, error handling, and rate limit logic. The Metapi version is 7 lines. And the Metapi version returns more complete data, including creative asset URLs that the Meta API doesn't provide.

FAQ: Facebook Ad Library API