If you're running ads on Meta's platforms, you've probably wondered what your competitors are doing. What creatives are they testing? What messaging works? How much are they spending?
The Facebook Ads Library gives you some of those answers. But manually clicking through ads one by one? That's not scalable. That's where the Facebook Ads Library API comes in.
The Ad Library API searches eligible public ad records. It does not expose every commercial ad worldwide or your competitors’ private performance metrics. Confirm coverage before building a research pipeline.
The short version of how to use it: verify your identity with Meta, spin up a developer app, generate an access token, then call the ads_archive endpoint with the filters you need. It's free to use, there's no paid tier, and you don't have to submit your app for review. The catch is what's actually in the archive, which we'll get into.
This guide covers everything: what the API is, how to get access, what data you actually get for free, the filtering parameters that matter, and working query examples you can copy. By the end, you'll know exactly how to use this transparency tool in 2026.
Quick note: The Ad Library API is completely different from Facebook's Marketing API. The Marketing API manages your own campaigns (creating ads, pulling performance data). The Ad Library API is read-only access to publicly visible ads for transparency purposes. Keep that distinction clear.
What Ads Can the Ad Library API Actually Return?
| Ad records | Official coverage | Use this distinction |
|---|---|---|
| Social issues, elections and politics | Delivered worldwide during the past seven years | Historical political-ad research |
| All ad types delivered in the UK or EU | Delivered during the past year | Commercial research within the covered regions |
| Currently running commercial ads outside that coverage | Not a worldwide commercial API archive | Use the Ad Library website for its broader active-ad search |
| Your own account’s spend, purchases and CPA | Marketing API, with account authorisation | Not public competitor performance data |
This follows Meta’s API overview, checked 31 October 2026. ad_type=ALL and a broad country filter do not expand the archive’s eligibility. A result can lack fields because those fields do not apply to that ad category or region.

What Is the Facebook Ads Library API?
The Facebook Ads Library API is an official Graph API endpoint that lets you search Meta's Ad Library database programmatically.
Meta launched the Ad Library (previously called Facebook Ad Library) to increase transparency around advertising, especially political ads. Through the public website, anyone can search for ads by keyword or advertiser name and see basic details like creative content, start dates, and which Page ran the ad.
The API extends this capability by letting software perform these searches automatically and return results in JSON format for analysis.
What Ads Are Included in the Archive?
The Ad Library isn't a complete record of every ad ever run on Facebook. It has specific transparency scopes based on ad type and geography.
Political and Issue Ads (Worldwide)
Any ad about social issues, elections, or politics gets archived globally and kept for 7 years. This includes ads Meta labels as political or issue-based (which requires advertisers to complete identity verification and disclaimer processes).
If you're researching election campaigns or advocacy messages, those are all catalogued regardless of country.
All Ads Delivered in Certain Regions
All ads delivered to users in the United Kingdom or European Union in the past year are included in the Ad Library. This is driven largely by EU regulations demanding greater ad transparency.
In practice: if an advertiser ran a regular product ad in France, that ad will be searchable via the library for up to one year after delivery.
Special Regional Cases
Meta provides data for other regions in line with local transparency laws. For example, ads delivered in Brazil that fall under political and issue categories are included (with some Brazil-specific metrics available).
But here's the key limitation: for most countries outside the UK/EU, non-political ads aren't archived. A regular shoe ad shown only in the US won't appear in the Ad Library unless it was labeled political/issue or also targeted Europe.
Critical to understand: The Ad Library API is primarily a transparency tool, not a universal ads spy tool. It's incredibly useful for what it covers, but it doesn't give you every ad worldwide.
Marketers monitoring competitors should note that you'll often only find competitors' ads if those ads were shown in EU/UK markets or categorized as political/issue. This is intentional. The library focuses on areas where transparency is legally or socially required.
Why Use the Facebook Ads Library API?
The API benefits several groups:
Researchers and Journalists
The API provides a goldmine for academics, journalists, and watchdog organizations analyzing political advertising, social issue campaigns, or ad trends.
Instead of manually checking the Ad Library web interface, they can programmatically collect data on thousands of ads. For example, all climate-change-related political ads in the past year can be pulled and analyzed for spend patterns, messaging themes, and targeting demographics.
Marketers and Advertisers
While the scope is limited to certain ads, it's still powerful for competitive intelligence and creative strategy.
You can use it to:
• Discover messaging and creatives competitors are running in different markets
• Identify trends in ad copy or creative approaches in your industry
• Find inspiration from top-performing ads by searching keywords or brands
• Validate strategies by seeing what others are doing
For example, if you're planning a holiday campaign, search last year's holiday ads in your sector via the API to spot common themes and opportunities for differentiation.
Agencies and Ad Tech Tools
Agencies managing many clients, or platforms like AdManage, can use the API to build internal dashboards or alerts.
You could automatically track a list of competitor Pages and get notified when new ads launch. This beats manual monitoring and ensures you don't miss important competitor moves.
Policy and Compliance Teams
Organizations can monitor how political or issue ads are being used, ensuring compliance with local laws. Advocacy groups can track how causes or candidates are being promoted on Meta's platforms.

API vs Website: Why Automate Your Research?
Simple: scale and automation.
The web interface works fine for one-off searches, but it's not built for deep analysis. The API lets you:
• Export data on hundreds or thousands of ads
• Filter and sort programmatically
• Integrate with databases or analysis tools
• Update results automatically on a schedule
A researcher could pull all ads mentioning a specific candidate across multiple countries and analyze spend and impression patterns in Python or R. A marketer using AdManage could automatically fetch any new ads from competitor Pages each week and review them in a dashboard.
These tasks are impractical without an API.
But the Ad Library API has significant limitations. It won't give you everything a marketer might dream of. It's not a backdoor to see competitors' ROI or precise targeting details beyond broad categories. It's first and foremost a transparency tool.
Let's look at exactly what data it provides.
What Data Can You Get from the API?
Before you start using the API, you need to understand what information you'll actually get. The data falls into two categories: basic ad info available for all ads, and detailed info available only for certain ads (political/issue or EU/UK ads).
Basic Information (Available for All Ads)
Every ad record includes:
A unique identifier for the ad in the library database. This ID is specific to the Ad Library (not the same as an advertiser's internal campaign ID).

Ad Creative Content
The actual text and components of the ad:
• Ad Creative Body Text: The main text of the ad creative
• Headline and Link Description: Provided as lists to account for carousel variations
• Call-to-Action Link Caption: Any caption on the CTA button or link area
Whether the ad uses image, video, meme format, etc. The field publisher_platforms lists where the ad appeared (Facebook, Instagram, Messenger, Audience Network).
A URL to see the archived ad as it appeared, including images or videos. This is essentially a permalink to an ad preview page.
Important: While you can manually download assets from this page, the API does not directly give you image or video files as a response payload. You'd have to use the snapshot URL and then capture content if needed.
The Facebook Page that ran the ad, identified by name and numeric ID. This tells you which organization or brand is behind the ad.
Ad Delivery Start and End Dates
When the ad started running, and if inactive, when it stopped. These timestamps are in UTC. If an ad is still active, the stop time may be blank.
You can filter by active status when querying. By default, queries return ads currently active unless you specify otherwise.
A list of Meta platforms where the ad was served (Facebook, Instagram, Messenger, Audience Network).
This basic set lets you see ad content, timing, and who ran it. For many marketing uses, this is the most relevant information: you can read competitor ads, see their images via snapshot links, and know when and where they ran.
Additional Information (For Political Ads and EU/UK Ads)
For ads categorized as political/issue or any ads delivered in the UK/EU, Meta provides extra transparency data:
A range estimate of advertiser spend on that ad, given in predefined buckets:
| Spend Bucket | Range |
|---|---|
| Lowest | <100 |
| Low | 100-499 |
| Medium-Low | 500-999 |
| Medium | 1K-5K |
| High | >1M |
Spend ranges are provided for eligible political and social-issue records. Do not assume that every commercial ad delivered in the UK or EU includes spend data.
Political and social-issue records can include impression ranges. For UK/EU commercial ads, use the estimated impression and reach fields supported for that region. An impression is not necessarily a distinct person.
Political-ad demographic distribution and UK/EU reach breakdowns use different regional fields. Inspect the returned structure and units before treating a value as a percentage, an impression total or a reach estimate.
These are aggregated transparency breakdowns, not individual viewer identities. Field availability and measurement definitions differ by ad category and region.
Geographic Reach
Use the currently documented regional reach fields where available. eu_total_reach is EU-specific; total_reach_by_location supports covered locations including the EU, UK and Brazil. Do not assume one field represents worldwide reach.
For political ads, you can get region (state/province) level data via delivery_by_region.
Political and social-issue records can contain a funding disclaimer in bylines. Meta separately lists beneficiary and payer information for EU ads. Check the regional field rules instead of assuming the same disclosure is available for every UK or commercial record.
Targeting Criteria (EU/UK Only)
Unique to ads delivered in the EU (and some UK ads), the library shows some targeting parameters:
• Target Age Range: The age targeting set (e.g., "18-65+" or "25-44")
• Target Gender: Whether the ad targeted men, women, or all
• Target Locations: Locations targeted or excluded (country/region level)
A commercial ad delivered in France can have eligible EU transparency fields, but that does not guarantee a spend range. A commercial ad delivered only in the US is outside the API’s general UK/EU commercial coverage; the Ad Library website has a broader active-ad search.
What Data Is NOT Included
Equally important is knowing what the API doesn't provide:
No Performance Metrics
You won't get clicks, click-through rates, conversions, or any KPIs advertisers use for optimization. The library is about transparency, not performance. It doesn't tell you if an ad was "successful" beyond the proxy of spend and impressions (given in ranges, not exact figures).
No Granular Targeting Info
You can't see detailed targeting choices like interests or behaviors, nor any custom audience info. The only targeting data is broad age/gender/location breakdown for reach, and in EU ads, high-level criteria (age range, gender, locations set).
There's no way to reverse-engineer exactly how the advertiser targeted users.
No User Data
You cannot see who saw or interacted with the ad on an individual level. All data is aggregated.
Limited Creative Media Retrieval
The API won't directly give you image or video files. The snapshot URL lets you view one ad at a time in a browser. If you need to bulk download ad creatives, you'd have to script something to hit those snapshot URLs individually (which is not officially supported and may violate terms).
Many third-party tools providing "ad creative scraping" are automating the web interface rather than using the API.
Limited Advertiser Info
Aside from Page name and ID, you don't get other info about the advertiser's profile. If you want Page category or verification status, you'd have to separately query the Graph API for the Page node (which might require different permissions).
Historical Data Limits
Non-political ads are only kept for 1 year (and only in EU/UK). You can't fetch, say, a 2019 commercial ad via the API if it wasn't political. Political ads go back 7 years, but anything pre-2018 is out of luck.
Also, if an ad was active beyond the one-year window, it disappears after a year of its last impression (for non-political).
Regional Gaps
As emphasized, ads not touching EU and not political are invisible here. If you're a marketer in Latin America looking to analyze competitors' local ads, the API might not help unless those competitors also run campaigns in Europe or label ads as social issues.
Meta's Transparency Center does have a Content Library API for posts and some region-specific archives, but for ads specifically, the above rules apply.
How to Get Access to the API (and Is It Free?)
Short answer: the Facebook Ad Library API is free, and you get access by verifying your identity with Meta, creating a developer app, and generating an access token. There's no paid tier and no App Review to clear. The one requirement people trip on is identity verification, which is mandatory because the archive includes political ad data.
Unlike some open APIs, this one isn't immediately accessible. You go through a short setup on Meta's developer platform first.
Here are the steps:
1. Confirm Your Identity and Location
Because the Ad Library includes sensitive political ad data, Meta requires developers to verify their identity and country before using the API.
Go to Facebook's identity confirmation page (facebook.com/ID) and follow the prompts. You may be asked to:
• Upload a government-issued ID
• Take a selfie
• Provide proof of residency
This process can take a couple of days (sometimes hours). This verification is typically one-time. Once approved, your Facebook account is authorized to access the Ad Library API.

This confirmation is required specifically for accessing social issues, election, or politics ad data, which effectively covers the API's scope.
2. Create a Meta Developer Account and App
If you haven't used Meta's developer platform, sign up at Meta for Developers and create a developer account. This means agreeing to platform policies and providing basic info.
Once done, create a new "App" in the developer dashboard. When creating an app, choose the simplest type (a "Consumer" app with no specialized products works fine).
The app is essentially a container for your API usage. It gives you an App ID and allows you to generate access tokens.
You do not need to submit this app for special approval to use the Ad Library API, since you're not requesting private user data. But you do need to have completed Step 1 (ID verification) or the Ad Library endpoints will return errors.
3. Generate an Access Token
Once your developer app is set up, you'll need an access token to authenticate API calls.
The Ad Library API can be accessed with a User access token associated with your verified Facebook account. The easiest way to get one initially is via the Graph API Explorer tool in the Developer dashboard.
Navigate to Tools → Graph API Explorer. Select your app and generate a user token with needed permissions. For the Ad Library, you don't need extended permissions like ads_read. A basic user token works as long as your user is verified for Ad Library access.
In Graph API Explorer, click "Generate Access Token". It will ask for permissions, but for Ad Library queries you typically only need default public data access.
Once you have the token, test it. In Graph Explorer, try the query:
plain text
ads_archive?ad_reached_countries=US&ad_type=POLITICAL_AND_ISSUE_ADS&search_terms="test"If you get data back and not an error, you're all set.
Important Notes on Access Tokens and Setup
Token Expiration
By default, Graph API Explorer tokens are short-lived (about 1-2 hours). For serious use, you'll want to extend the token to a long-lived token, which lasts about 60 days.
You can do this in the developer portal (under Access Token Tools, or by clicking the info icon next to the token in Graph Explorer and choosing "Extend Access Token"). This extended token can be used in your scripts. You'll need to regenerate or refresh it after expiration.
App Review
The Ad Library API endpoints do not require your app to go through the rigorous App Review process needed for accessing private user data or advertising account data. You're accessing public archive info, so as long as your user is verified, you're fine.
Rate Limiting
Every app has Graph API rate limits. Meta doesn't publicly state exact rate limits for these endpoints, but they're generally based on number of calls per hour per user/token and overall calls per app.
If you plan to pull huge volumes (tens of thousands of ads), be mindful of potential throttling. Queries that return large data sets might hit timeouts more than strict rate call limits.
API Version
Facebook version-names its Graph API. The Ad Library was introduced around Graph API v3.2 (2018). By 2026, the Graph API is well past v23.0 (Meta ships new versions a few times a year).
You should use the latest version for new projects. The endpoints and fields we discuss are available in recent versions. Using an older version might work but could be deprecated sooner.
The endpoint path includes the version, like:
plain text
https://graph.facebook.com/<SUPPORTED_API_VERSION>/ads_archive?....Always check Meta's developer changelogs for tweaks to Ad Library fields in new versions.
Once you have your identity confirmed, app created, and token in hand, you're ready to make queries!
How to Query the API (Step-by-Step)
The Ad Library API is accessed via the Graph API's ads_archive endpoint. When you call this endpoint with proper parameters, you'll get back a JSON object containing an array of ads matching your query.
Endpoint URL
plain text
https://graph.facebook.com/<API_VERSION>/ads_archiveReplace <API_VERSION> with a currently supported version and confirm fields, access and filters in Meta’s endpoint reference. Keep tokens out of source control and logs; the examples below use an Authorization header.
Required Parameters
Every query needs:
access_token
Your user access token (can be a URL query param or HTTP header).
This defines the country scope for ads you want to retrieve. You can set it to one or more country codes, or "ALL" for all. This is required because of how the archive is segmented by region.
A country filter scopes the ads’ delivery locations. Use the markets you actually need; ALL does not turn the endpoint into a worldwide commercial archive.
Meta’s current overview includes all ad types delivered in the UK or EU during the past year and political/social-issue ads delivered worldwide during the past seven years. Check that coverage separately from the country parameter.
For example: ad_reached_countries=['US'] plus ad_type=ALL will effectively return only political/issue ads in the US (because non-political US ads aren't archived). By contrast, ad_reached_countries=['GB'] could return any ads delivered in the UK, political or commercial.
Start with one eligible market and a narrow date range, then expand deliberately. Store the requested countries and filters with your results so a later comparison uses the same scope.
Important Filtering Parameters
The API offers various parameters to refine your search:
A keyword or phrase to search within ad text. This functions similar to the search box on the Ad Library website.
If you provide multiple words without quotes, it treats them as an unordered "AND" query by default (all words must appear somewhere, in any order).
You can also specify search_type=KEYWORD_EXACT_PHRASE if you want exact phrase match. For example, search_terms="electric car" with exact phrase vs. separate keywords.
For exact phrases, use the documented search_type value. Do not assume punctuation creates OR logic; run separate searches and deduplicate by Library ID when you need a union of terms.
search_terms is very useful if you're looking for ads containing certain brand names, slogans, or topics. If you leave it blank, you must use some other filter like page IDs, otherwise the query might be too broad.
You can directly search by specific Facebook Page IDs (up to 10 at a time). This is extremely helpful for pulling all ads from a particular advertiser.
For example, if Nike's Facebook Page ID is 12345, you could query search_page_ids=["12345"] along with ad_reached_countries=['ALL'] to get Nike's ads.
Keep in mind: if that Page hasn't run ads in your specified region/time window, you might get empty data. Use the numeric Page ID, not the vanity name.
Filter by whether ads are currently active or not. Options: ACTIVE, INACTIVE, or ALL.
By default, the API only returns active ads unless you change this. If you want to find past ads (that have ended), set ad_active_status=ALL or INACTIVE.
For historical analysis (like "what did my competitor run last holiday season?"), you definitely want ALL because those ads might now be inactive.
Filter by special ad categories:
Political and social-issue ads: POLITICAL_AND_ISSUE_ADS.
Housing ads: HOUSING_ADS. Employment ads: EMPLOYMENT_ADS.
Financial products and services: FINANCIAL_PRODUCTS_AND_SERVICES_ADS.
All eligible ad categories: ALL. This filter does not broaden the API’s country and historical coverage.
By default this is ALL (which includes normal ads and everything). You might use this if you only want to pull political ads and exclude commercial: set ad_type=POLITICAL_AND_ISSUE_ADS.
Or if you specifically wanted to see ads in regulated categories like housing, jobs, or credit offers, use those enums.
Note: the category "CREDIT_ADS" was deprecated and merged into financial products.
Filter by whether the ad contains an image, video, etc. Options: IMAGE, VIDEO, MEME, NONE, or ALL.
Handy if you only want video ads for inspiration, or only static image ads.
Filter ads by the language of ad text content. Provide language codes (e.g., ['en'] for English, ['es','en'] for either Spanish or English).
This helps narrow results especially in multilingual regions.
ad_delivery_date_min and ad_delivery_date_max
Specify a date range for when the ad was delivered. Format: YYYY-MM-DD.
This filters ads that were active on or after the min date and on or before the max date. If you want to find ads that ran during Black Friday weekend 2024, set min of 2024-11-24 and max of 2024-11-30.
Note this uses ad delivery dates (when impressions happened), not necessarily creation time.
Specify one or more of Meta's platforms (FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER) to only get ads that ran there.
For instance, filter to only Instagram ads by a competitor if you want to analyze their IG strategy separate from Facebook.
A less common parameter (boolean) that, if true, will reveal content that was removed for policy violations.
By default, if an ad was taken down for hate speech, the library might mask or not show removed content. This flag would show it.
Use with caution and only if needed for research, as removed content may be sensitive and likely not relevant for most marketing uses.
You can combine multiple filters in one query (e.g., search by page ID and keyword and date range) to refine exactly what you need.
Response Fields
Request the fields you need explicitly, such as id, page_id, page_name, ad_creative_bodies, ad_snapshot_url and delivery dates. Confirm current names and availability in the endpoint reference.
If you want additional fields (spend, impressions, demographics), specify a fields parameter:
plain text
fields=id,page_id,page_name,ad_creative_bodies,ad_snapshot_url,spend,impressions,demographic_distributionRequesting a field does not guarantee it exists for every ad. Political records can include spend and impression ranges; UK/EU commercial transparency fields differ. Missing spend does not mean zero spend.
Example Query
For a minimal commercial-research example, search ads delivered in Great Britain containing “electric car”. This is a covered-market example, not an exhaustive worldwide automotive export.
Begin with common identity and creative fields. Add eligible transparency fields only after checking the category and regional field rules.
Parameters:
• search_terms="electric car"
• ad_type=ALL
• ad_active_status=ALL (to include inactive ones)
• ad_reached_countries=["GB"]
• fields: id, page_id, page_name, ad_creative_bodies, ad_snapshot_url.
Call:
plain text
GET https://graph.facebook.com/<API_VERSION>/ads_archive?search_terms=electric%20car&ad_type=ALL&ad_active_status=ALL&ad_reached_countries=%5B%22GB%22%5D&fields=id,page_id,page_name,ad_creative_bodies,ad_snapshot_url
Authorization: Bearer <ACCESS_TOKEN>In practice, you'd URL-encode this or use curl. Here's how it might look:
bash
curl -G "https://graph.facebook.com/<API_VERSION>/ads_archive" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
--data-urlencode "search_terms=electric car" \
--data-urlencode "ad_type=ALL" \
--data-urlencode "ad_active_status=ALL" \
--data-urlencode 'ad_reached_countries=["GB"]' \
--data-urlencode "fields=id,page_id,page_name,ad_creative_bodies,ad_snapshot_url"This returns a JSON response containing a data array of ad objects matching those filters. Each object would have page_name, page_id, ad_creative_bodies (list of text snippets), etc.
Do not interpret political-ad spend ranges as exact budgets, and do not expect those same spend fields for every UK/EU commercial record. Public transparency data does not provide competitor purchase CPA or ROAS.
Pagination
Meta’s API FAQ states that a results page can return a maximum of 5,000 ads and that matching results continue through pagination. This is a per-page ceiling, not a guarantee that a maximum-sized page is efficient for every query.
If there are more matching ads beyond your limit, the JSON includes a paging section with a next URL. You can use that to retrieve the next batch, and so on, until you've gotten all results.
For a large research extract, use narrow filters and a manageable page size. Follow paging links until exhausted and deduplicate records by Library ID; preserve filters and fetch timestamps.
If a page times out, reduce page size and date scope. Use bounded retries for transient failures, and keep credentials out of logs when recording paging URLs.
A completed export means every available page for that query has been processed. It does not prove that the API covers every ad the advertiser has ever run.
Handling "No Results"
If your query is too broad and outside the library scope, you might get an empty data set.
A US query can still match eligible political or social-issue ads. An empty response does not prove that the advertiser ran no ads; check coverage, country, dates, Page ID and active-status filters before drawing that conclusion.
In such cases, refine your query or understand the limitations (maybe the advertiser you searched doesn't have EU ads). The API won't necessarily tell you "we only show EU/political" (it just returns no data if nothing matches).
By using the right combination of filters, you can fetch precisely the data you need.
Best Practices for Using the API
1. Narrow Your Queries for Efficiency
The Ad Library API can return large volumes of data, especially if you search common terms (imagine how many ads contain the word "sale" in a year).
To avoid being overwhelmed or hitting performance issues:
• Limit by country when possible. If you only care about a certain market, use that country code instead of "ALL". For instance, ad_reached_countries=['GB'] for UK ads or ['US'] for U.S. political ads.
• Use date ranges to slice data. Rather than pulling an entire year in one go, pull month by month using date min/max filters. This also helps if you plan to regularly update data (e.g., fetch last 7 days of ads every week).
• When looking for a specific advertiser, search_page_ids is your friend. That ensures you only get that page's ads, which is much cleaner than keyword searching their brand name (which might also pull unrelated results).
• Combine keywords with category filters. If you search "insurance", expect thousands of ads. But maybe you only want political issue ads about insurance; then include ad_type=POLITICAL_AND_ISSUE_ADS. Or only housing ads with "insurance" with ad_type=HOUSING_ADS.
2. Be Mindful of the One-Year Window for Commercial Ads
If you're researching historical trends for non-political ads, remember you'll only get the last year of data (for EU/UK-delivered ads).
If today is November 17, 2025, the library will have roughly back to November 2024 for EU/UK ads. Anything older has rolled out of the archive. Political ads are available back to 2018.
Plan your analysis accordingly. If you need to "save" data over time, consider setting up a routine to periodically fetch new ads and store them elsewhere, effectively building your own longer archive for a particular topic or advertiser.
3. Use the Graph API Explorer for Trial and Error
The Graph API Explorer tool on developers.facebook.com is extremely handy to test your queries and see quick results in a nice format.
You can experiment with different parameters (it even has an interface for selecting fields) and see the JSON instantly. This is much faster for iteration than writing code immediately.
Once your query is giving you what you want in the Explorer, translate it into code or a script. It also helps with getting the token and making sure your app is selected properly.
4. Handle Pagination in Your Code
If you're scripting data collection (e.g., in Python or using cURL + jq), make sure you follow the paging.next links until exhausted, or use the after cursor from paging.cursors to loop.
Some libraries or SDKs can abstract this for you. If you intentionally only want the first X results, use the limit param accordingly and don't page further.
5. Manage Your Access Token Securely and Refresh It
Do not expose your access token in public code or URLs (treat it like a password).
If it's a long-running project, remember to refresh the token at least every 60 days (or implement an OAuth refresh flow). If the token expires, your requests will suddenly fail with an OAuth error.
Some guides recommend extending token life via the developer dashboard to the maximum 90 days and even suggest setting up a cron job or mechanism to update it periodically.
If you're just doing a one-off data pull, a single token might suffice. For continual use, plan for renewal.
6. Respect Usage Limits and Terms
If you start hitting rate limits (you might get responses with error code 4 or 17 indicating throttling), slow down your request rate or batch your queries.
Meta's platform policy also requires that data from the Ad Library is not used for nefarious purposes. Since this is public data, you have a lot of leeway for analysis, but do read the Ad Library API Terms of Service.
For example, Meta might forbid building a service that republishes the data in a misleading way or using it to profile individuals.
Generally, if you're using it for research, journalism, or internal marketing insights, you're in safe territory. If you plan to display the data publicly (say, on a website that compares political ads), ensure you include proper disclaimers and attributions per Facebook's terms.
7. Combine with Other Tools for Deeper Analysis
The Ad Library API data can be exported to CSV, fed into a database, or even connected to Google Sheets with tools like AdManage's Google Sheets Add-on.
Think about how to integrate this with your workflow:
• If you're a marketer, you might maintain a Google Sheet of competitor ads, updated via the API.
• Data analysts might load JSON results into Python pandas dataframes or use R to analyze patterns.
• You could mash up Ad Library data with your own performance data. For example, compare how your ads differ from competitors' ads in messaging or frequency.
Keep in mind the API's data is aggregate. For instance, you might see a competitor spent "$50K–100K" on an ad. You can't get the exact figure, but even ranges over time can show trends (e.g., if they had many ads in Q4 in the top spend bucket, they likely poured a lot into holiday campaigns).
8. Workaround for Finding Specific Ads
One quirk: you cannot directly query a single ad by its Library ID. The Graph API doesn't provide an endpoint like ads_archive/<adID>. You always have to search.
If you have an ad's ID and want its data, the workaround is to search by the Page and then filter client-side for that ID, or use specific search terms unique to that ad.
Some community-built tools allow a function like findByAdId(adId, pageId) by doing the heavy lifting (it basically fetches the page's ads and finds the match).
For most people, this is not a big issue, but just be aware you can't do a direct lookup by ID through the API.
9. Use Multiple Queries for Broad Coverage
If you want to cover all ads of a certain type, you may need multiple queries.
Example: to get all political ads globally in the last month, you might break it down by country or region because just doing ALL could be huge.
You could iterate over country codes (especially those with a lot of political ads, like US, BR, IN) or use filters like delivery_by_region for US states if needed.
The API isn't really intended for dumping the entire archive in one go, so think in terms of sensible slices.
10. Stay Updated with Policy Changes
The world of social media advertising is heavily influenced by regulations and platform policies. Meta sometimes changes what data is available.
A notable recent example: as of October 2025, Meta has stopped allowing new political, electoral, and social issue ads in the EU entirely due to new EU regulations (the Transparency and Targeting of Political Advertising law).
This means the Ad Library in the EU will not have new entries for political ads going forward (existing ones remain archived).
If you were building a tool to monitor political ads for the 2026 EU elections, this policy essentially freezes that data (something you'd want to know!).
Always keep an eye on Meta's developer announcements or policy news. For instance, if new regions come under transparency requirements, Meta might expand the Ad Library coverage (or if they dial back some features).
Checking the official Release Notes for the Ad Library API occasionally is a good idea.
How AdManage Turns API Insights into Action
Now that you understand the power of the Facebook Ads Library API, let's talk about how to turn that competitive intelligence into actual campaign execution.
The API gives you incredible visibility into competitor strategies. But what do you do with that information? How do you rapidly test what you've learned without drowning in manual ad creation?
This is where AdManage transforms your workflow.
The Competitive Intelligence → Execution Gap
Here's the typical workflow problem:
① You use the Ad Library API to discover competitors are testing 50+ creative variations for holiday campaigns
② You identify winning patterns in their messaging, creative formats, and offers
③ You realize you need to test similar volumes to compete
④ Then reality hits: Manually creating 50+ ad variations in Ads Manager will take days
⑤ By the time you launch, the competitive moment has passed
AdManage solves this execution bottleneck.
Bulk Launch What You Learn
AdManage is built specifically for teams that need to launch hundreds or thousands of ad variations quickly. Here's how it complements Ad Library API research:
Speed at Scale
When the API shows competitors testing 20+ variations of holiday messaging, AdManage lets you bulk-launch your own test matrix in minutes, not days. Upload creative assets, set naming conventions, configure UTM parameters, and launch across Meta and TikTok simultaneously.
Time-savings calculators use assumptions rather than measuring every advertiser's labor. For illustration, 1,000 ads at 10 minutes of manual setup each represent 166.7 hours; the time actually saved depends on the work your team still performs. Use current calculator inputs, your own timings and labor cost before judging a subscription's value.
Structured Execution
API research reveals patterns, but execution requires discipline. AdManage enforces naming conventions, UTM management, and creative grouping by aspect ratio automatically.
When you discover a competitor's winning formula via the API, you can systematically test variations without the chaos of inconsistent naming or broken tracking.
Social Proof Preservation
One of the most valuable API insights is seeing which competitor ads have been running for months (high spend + long duration = likely winner).
When you find your own winners, AdManage's Post ID preservation lets you scale them without losing accumulated social proof (likes, comments, shares).
Multi-Platform Testing
The Ad Library API shows you Facebook and Instagram activity. But top advertisers test across platforms.
AdManage lets you launch the same creative variations to both Meta and TikTok, letting you test whether insights from one platform translate to another.
Real-World Workflow Example
Let's say you're in e-commerce, preparing for Black Friday.
Week 1: Research
Use the Ad Library API to:
• Pull all ads from top 10 competitors in your category
• Filter for ads delivered September-November (pre-holiday testing)
• Analyze creative patterns: discount messaging, urgency tactics, creative formats
• Identify which competitors ran high-spend campaigns (those spend ranges tell a story)
Week 2: Strategic Planning
Based on API insights:
• You discover 70% of competitor ads use countdown timers in creative
• Top spenders are testing 3 discount tiers: 20%, 30%, 40%
• Video ads outnumber static 3:1 in the high-spend bracket
• Instagram placement dominates (80% of ads include IG)
Week 3: Execution with AdManage
You need to test:
• 3 discount tiers × 5 creative variations × 2 formats (video/static) = 30 variations
• Across Facebook and Instagram
• With proper UTM tracking for each
• Launch as paused for approval before going live
① Upload your 10 creative assets (5 concepts, each in video and static)
② Set naming convention: BF2025_{Discount}_{CreativeID}_{Format}
③ Configure UTM parameters: source=meta&campaign=blackfriday&content={Discount}_{CreativeID}
④ Set creative enhancement toggles per account
⑤ Bulk launch 30+ variations to Meta in under 10 minutes
⑥ Use bulk preview links for team approvals
⑦ Go live once approved
Total time: About 30 minutes vs. 10+ hours manually.
Integration Opportunities
AdManage integrates with Google Sheets, Google Drive, Zapier, and Make.com.
You could build a workflow where:
① Python script queries Ad Library API weekly
② Exports competitor ad data to Google Sheets
③ Team reviews and flags patterns
④ AdManage Google Sheets Add-on launches test campaigns based on those patterns
⑤ Slack notifications alert you when AdManage launches hit performance thresholds
This creates a continuous competitive intelligence → execution loop.
Who Benefits Most?
Performance Marketers at D2C Brands
If you're running creative testing at scale (hundreds of variations monthly), the combination of Ad Library API research + AdManage execution is powerful.
You can rapidly iterate based on what competitors are doing while maintaining the throughput needed to find breakout creatives.
Agencies Managing Multiple Clients
AdManage currently starts at £199.99/month for Essential, with 1 Meta ad account. In-house starts at £499.99/month with 5 ad accounts; Agency starts at £999.99/month with 10. Enterprise has custom unlimited-account arrangements. Channel access, AI credits, team allowances and money-back terms vary by plan; check the live pricing page.
Account-level defaults for naming and UTMs ensure consistency across clients.
Enterprise Teams with Governance Needs
AdManage's enterprise plan adds custom terms on top of unlimited ad accounts. Combined with API-driven competitive research, you get the intelligence and the throughput to act on it across a large team.
Pricing That Makes Sense
Unlike ad platforms that charge based on spend, AdManage uses fixed monthly pricing:
For current AdManage plans, prices and account allowances, see the pricing page. Check billing period, included accounts and any agreed enterprise terms before comparing costs.
When you're using the Ad Library API to research and then need to launch competitive responses quickly, that fixed fee structure means your research → execution costs are predictable regardless of how many tests you run.
Recent API Updates You Should Know
A few developments over the last couple of years still shape how you use the Ad Library API in 2026. Here's what matters:
Regulatory Changes: EU Political Ads Ban
Meta made a major policy decision in response to the EU's Transparency and Targeting of Political Advertising (TTPA) regulation.
Effective early October 2025, Meta no longer allows any political, electoral, or social issue ads in the European Union.
This was a reaction to new requirements the EU planned to enforce, which Meta deemed too onerous or uncertain.
From a data perspective: The Ad Library (and API) will have no new EU-based political ads after that date. All historical data up to that point remains (the API still provides the up to 7-year archive for those ads).
But if you query for political ads in France in November 2025 or 2026, you'll likely get zero results because none are running.
This is a significant change for researchers: effectively the EU archive is now static after October 2025 for the political category. Outside the EU, political ads continue as usual (and remain accessible via the API where allowed).
API Version Updates
In May 2025, Meta released Graph API v23.0 (and Marketing API v23.0) as part of their versioning cycle.
While most changes were for the marketing side, it "set a new baseline" for integration with the Ad Library, essentially ensuring continued support.
No drastic changes in how the Ad Library API works were introduced. Still, always check the changelog.
For example, older fields or values might be deprecated over time. One change around 2024 was renaming the credit ads category to the broader financial services category in ad_type filter (a minor update but worth noting if you used the old value).
Content Library API
In mid-2025 Meta also updated their Content Library and API. This is separate from the Ad Library (it deals with organic content (posts) from Pages and is used for transparency and research on things like popular posts or misinformation tracking).
If your analysis crosses over (for instance, you want to see both the ads and the regular posts a politician is making), you might look into the Content Library API too.
Increased Transparency Fields
Meta occasionally adds new fields to the Ad Library. For example, a relatively recent addition was the breakdown of reach for Brazil and the UK separately (fields like br_total_reach, eu_total_reach, and reach by region).
These came as Meta adapted to local laws (Brazil required similar transparency for political ads around their elections).
Keep an eye out for new fields in the official documentation. In 2025, much of this is stable, but should Meta include new platforms (e.g., if Threads were to have an ads section, theoretically they'd include that under publisher_platforms) or new ad formats, the library might adjust.
Special Ad Categories Enforcement
If you're querying by ad_type for Housing, Employment, or Financial ads, recall that these categories exist due to anti-discrimination policy enforcement.
Meta might refine what falls into those categories. For instance, an update could expand definitions or add another category if regulation demands it.
So far, the four categories (political, housing, employment, credit/financial) are it.
Third-Party Tools
A vibrant ecosystem emerged around the Ad Library. By 2025, various tools (some open source, some commercial) provide easier ways to scrape or query the Ad Library.
For instance, browser extensions that let you save ads, or APIs that claim to pull any page's ads easily (likely by combining official API with unofficial scraping).
While this guide sticks to the official API, be aware of these options. They often exist to circumvent the "must target EU or be political" limitation by scraping the web interface for ads in other regions.
Use at your own risk. Scraping the Ad Library website might violate terms of service, whereas using the official API within its allowed scope is safer legally.
Meta has not signaled any intention to broaden the API to all ads globally (because that would violate their own user privacy considerations and regional laws), so these third-party solutions fill a demand for marketing intel.
In summary, heading into 2026 the Ad Library API remains a key transparency tool with a stable feature set, aside from the big change of EU political ads availability.
Always double-check current documentation for any field changes, and be aware of the wider context (like the EU regulations) when interpreting the data you get.
Common Questions About the API

Where is the official Facebook Ads Library API documentation?
Meta hosts it in two places. The official Ad Library API reference covers access requirements and fields, and the Graph API ads_archive endpoint docs list every parameter and its exact syntax. Bookmark both. This guide is meant to sit alongside them: the docs tell you which fields exist, and the sections below tell you what the data actually looks like in practice and where the archive quietly leaves gaps.
What's the difference between the Facebook Ads Library API and the Facebook Marketing API?
The Marketing API lets you manage your own ad campaigns (creating ads, pulling performance metrics, optimizing). The Ad Library API provides read-only access to publicly available ads for transparency and research purposes.
Think of it this way: Marketing API is for running your ads, Ad Library API is for researching others' ads.
Is the Facebook Ads Library API free?
Yes. The Ad Library API is completely free to use, with no paid tier and no per-call charge. You only need a verified Facebook account, a developer app, and an access token. What you're really "paying" is the setup time for identity verification plus living with the archive's coverage limits (mostly EU/UK and political ads). If someone is charging you for "ad library data," they're either wrapping the free API or scraping the public web interface.
How many active ads is a competitor running? How do I find that?
Query the ads_archive endpoint with search_page_ids set to that advertiser's numeric Page ID and ad_active_status=ACTIVE, then count the records returned (page through the results if there are more than your limit). The same caveat applies: you'll only see their ads if those ads ran in the EU/UK or were political/issue. For a US-only commercial advertiser with no EU delivery, the count comes back empty even if they're running plenty of ads.
Can I see all competitor ads in any country?
No. The Ad Library API primarily shows:
• All ads delivered in the UK or EU in the past year
• Political and issue ads globally for the past 7 years
For most countries outside UK/EU, non-political ads aren't archived. A regular commercial ad running only in the US won't appear unless it's labeled political/issue or also targeted Europe.
How do I get exact spend and impressions data?
Political and social-issue records can include spend and impression ranges. UK/EU commercial ads have different estimated impression, reach and targeting fields; they do not universally expose spend.
Do not convert a range into an exact budget or treat an estimated audience figure as audited performance. The public API does not disclose competitors’ clicks, purchases, CPA or ROAS.
Do I need App Review to use the Ad Library API?
No. Since you're accessing public archive information (not private user data or ad account data), you don't need to submit your app for App Review.
You just need:
① Identity verification on Facebook
② A Meta developer account and app created
③ A valid access token
How long does identity verification take?
Typically a couple of days, sometimes hours. You'll upload a government-issued ID and possibly proof of residency.
Once approved, your Facebook account is authorized to access the API.
Can I download ad creative images and videos directly through the API?
Not directly. The API provides a ad_snapshot_url that lets you view the archived ad (including images/videos) in a browser.
You can manually download assets from that page for analysis, but the API response doesn't include the actual image or video files.
If you need to bulk download creatives, you'd have to script something to visit those snapshot URLs individually (which may violate terms if done improperly).
What happens when my access token expires?
Your API requests will fail with an OAuth error.
By default, Graph API Explorer tokens are short-lived (1-2 hours). You should extend them to long-lived tokens (about 60 days).
For continual use, set up a mechanism to refresh tokens periodically (like a cron job).
Can I query a single ad by its Library ID?
No. The API doesn't provide an endpoint like ads_archive/<adID>. You always have to search using filters like page IDs, keywords, or date ranges.
If you have an ad's ID and want its data, the workaround is to search by the Page and filter client-side for that ID.
How many results can I get per query?
Meta’s current FAQ lists a maximum of 5,000 ads per results page. Do not rely on the older 2,000-per-page figure previously stated in this guide.
Meta’s FAQ specifies up to 5,000 ads per results page, with pagination for additional matches. Use a manageable page size and process every page; a page-size limit is not the archive’s total record count.
Why am I getting no results for my query?
Common reasons:
• You're searching for non-political ads outside EU/UK. These aren't in the archive.
• The advertiser hasn't run ads in your specified region/time window.
• Your filters are too restrictive. Try broadening your search (e.g., change ad_active_status to ALL instead of just ACTIVE).
• The page ID is incorrect. Use the numeric Page ID, not the vanity name.
Can I use the Ad Library API for commercial purposes?
Yes, for research, analysis, and internal marketing insights. But you must comply with Meta's platform policies.
For example, Meta might forbid building a service that republishes the data in a misleading way or using it to profile individuals.
If you plan to display data publicly (like a website comparing political ads), ensure you include proper disclaimers and attributions per Facebook's terms.
Why did Meta stop political ads in the EU?
In October 2025, Meta stopped allowing new political, electoral, and social issue ads in the EU due to the EU's Transparency and Targeting of Political Advertising (TTPA) regulation.
Meta deemed the new requirements too onerous or uncertain to comply with. Existing political ads remain in the archive, but no new EU political ads will appear after October 2025.
Can I integrate the Ad Library API with Google Sheets?
Yes. AdManage's Google Sheets Add-on allows you to connect ad data to Google Sheets directly.
You can also build custom scripts (using Google Apps Script or external Python scripts) to query the API and populate Sheets.
Does the API show which audiences were targeted?
Only at a high level for EU/UK ads. For ads delivered in the EU, you get target age range, target gender, and target locations.
You cannot see detailed targeting choices like interests, behaviors, or custom audiences. The only targeting data is broad demographic breakdowns.
How often is the Ad Library data updated?
The Ad Library is updated regularly as ads run and stop. There's no official "refresh rate" published, but data typically appears within hours of an ad going live.
For your API queries, you're getting near-real-time data (with the caveat that inactive ads might take a bit to be marked as stopped).
Can I see engagement metrics like likes, comments, or shares?
No. The API doesn't provide engagement metrics. You only get:
• Creative content
• Delivery dates
• Spend/impressions ranges (for qualifying ads)
• Demographic reach percentages
Actual engagement data (likes, comments, shares, clicks) is not included.
How can AdManage help me act on Ad Library API insights?
AdManage solves the execution bottleneck after you've gathered competitive intelligence.
When the API shows competitors testing 50+ creative variations, AdManage lets you bulk-launch your own test matrix in minutes, not days.
You can:
• Bulk-launch hundreds of ad variations across Meta and TikTok
• Enforce naming conventions and UTM tracking automatically
• Preserve social proof with Post ID preservation when scaling winners
• Integrate with Google Sheets, Drive, Zapier, and Make.com
AdManage's fixed monthly pricing (£499.99 in-house, £999.99 agency) means your research → execution costs stay predictable regardless of test volume.
Start Using the Facebook Ads Library API Today
The Facebook Ads Library API is one of the most underutilized competitive intelligence tools available to marketers. While your competitors manually browse ads one by one, you can programmatically analyze thousands of ads, spot patterns, and identify winning strategies.
Here's your action plan:
Step 1: Get API Access
① Complete identity verification on Facebook
② Create a Meta developer account and app
③ Generate and extend your access token
④ Test your first query in Graph API Explorer
Step 2: Build Your Research Workflow
① Identify key competitors in your space
② Pull their Page IDs
③ Query the API for their active and recent ads
④ Analyze patterns in messaging, creative formats, and timing
⑤ Track spend ranges and duration to identify likely winners
Step 3: Turn Insights into Action
This is where most marketers fail. They gather intelligence but can't execute fast enough.
Use AdManage to bulk-launch test campaigns based on what you learn.
When you discover a competitor testing 30 variations of holiday messaging, AdManage lets you launch your own competitive response in under 10 minutes instead of spending days in Ads Manager.

View AdManage’s current plans and see how the combination of API-driven research + bulk execution transforms your advertising results.
The API gives you the intelligence. AdManage gives you the speed.
Cedric Yarish is a Meta ads expert, performance marketer and product builder with 10+ years of experience across Photoroom, Nextdoor and MVF. At Photoroom, he led user acquisition with more than $1 million in monthly ad spend and a creative operation producing 400 ads a month across 30 languages.
Today, he leads product and engineering at AdManage, the platform he co-founded with his brother Raphael to help marketers launch, test and manage ads at scale. Meta has quoted him on its developer blog and invited him to speak on its Partner API Panel in New York. His insights on creative testing and advertising automation have also featured in RevenueCat and In Growth We Trust.
Full founder bio & interviews

