How to Manage Ecommerce Product Catalogs? (2025)
Complete guide to ecommerce product catalog management. Centralize data, automate updates, and unlock dynamic ads on Meta, TikTok, and Google.
TABLE OF CONTENTS
Facebook Ads Library API: Complete Guide (2025)
Pull competitor ad data at scale with the Facebook Ads Library API. Complete 2025 setup guide, filtering strategies, and execution tips.
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.
This programmatic interface lets you query Meta's entire public ad archive at scale. Instead of browsing ads manually, you can pull thousands of records, analyze patterns, and build competitive intelligence dashboards. For marketers managing multiple campaigns (especially with tools like AdManage), the API becomes a research superpower.
This guide covers everything: what the API is, how to access it, what data you actually get, and how to use it effectively in 2025. By the end, you'll know exactly how to use this transparency tool for competitive advantage.
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 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:
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.
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 |
Only political/issue ads globally and any ads in UK/EU have spend data.
Similarly, ranges for impressions (views) like "1K-5K", "10K-50K", etc. Available for political/issue ads and UK/EU ads.
High-level breakdowns of who saw the ad by age and gender, expressed in percentages. For example, data might show an ad's audience was 60% male and 40% female, with 50% of viewers ages 25-34.
These breakdowns are available for political/issue ads and ads delivered in the EU/UK. They're aggregated (no personally identifiable info, just percentage buckets).
Geographic Reach
For multi-country campaigns, the API shows reach split by country or region. For EU ads, you get total EU reach and UK reach if applicable. Some country-specific metrics exist (Brazil's political ads have a br_total_reach field).
For political ads, you can get region (state/province) level data via delivery_by_region.
For political and issue ads, the API provides "Paid for by" disclaimer info showing who funded the ad. The fields bylines or beneficiary_payers contain this, especially for EU where both beneficiary and payer need disclosure.
Targeting Criteria (EU/UK Only)
Unique to ads delivered in the EU (and some UK ads), the library shows some targeting parameters:
These detailed fields are only present when applicable. A standard commercial ad for shoes running in France will have spend, impressions, and targeting info. The same shoe ad running only in the USA won't appear in the library at all (since it's not EU and not political).
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
Unlike some open APIs, the Facebook Ad Library API isn't immediately accessible. You must go through a setup process involving identity verification and Meta's developer platform.
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:
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 2025, the Graph API is on version 17+ (they do quarterly version bumps).
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:
https://graph.facebook.com/v18.0/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
https://graph.facebook.com/<API_VERSION>/ads_archive
Replace
<API_VERSION> with your target version (e.g., v18.0). All requests must include your access token and at least the required filters.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.
If you know you're looking for ads that ran in a specific country (say US or GB), you can narrow it. If you want to search the entire archive regardless of country, you can use ALL.
But note the caveat: using ALL will only return political/issue ads unless one of your specified countries is in EU. Ads that didn't reach any location in the EU will only return if they're about social issues, elections, or politics.
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). Meanwhile, ad_reached_countries=['GB'] could return any ads delivered in the UK, political or commercial.In practice, if you're doing a broad search and want all relevant ads, set
ad_reached_countries=["ALL"] and include ad_type=ALL. Or if you specifically want to capture everything in a certain market, do ad_reached_countries=['US','GB','CA'] (up to 10 country codes can be listed in one query array).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.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:
Category | Description |
POLITICAL_AND_ISSUE_ADS | Political, electoral, and social issue ads |
HOUSING_ADS | Housing-related ads (special category) |
EMPLOYMENT_ADS | Job-related ads (special category) |
FINANCIAL_PRODUCTS_AND_SERVICES_ADS | Credit, loans, banking ads |
ALL | Everything (default) |
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.
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
If you want additional fields (spend, impressions, demographics), specify a
fields parameter:fields=id,page_id,page_name,ad_creative_bodies,ad_snapshot_url,spend,impressions,demographic_distribution
Including such a fields list ensures you get those data points in the JSON. The Graph API will only return data that exists for a given ad; fields that don't apply (or you didn't request) won't appear.
Example Query
Let's construct a real example. Suppose you want to find active ads containing the term "electric car", across all countries. You're researching how automotive companies advertise electric vehicles.
You want both political issue ads and commercial ads in Europe.
Parameters:
•
search_terms="electric car"•
ad_type=ALL•
ad_active_status=ALL (to include inactive ones)•
ad_reached_countries=["ALL"]•
fields=page_name,page_id,ad_creative_bodies,ad_snapshot_url,spend,impressions,demographic_distributionCall:
GET https://graph.facebook.com/v18.0/ads_archive?search_terms="electric car"&ad_type=ALL&ad_active_status=ALL&ad_reached_countries=['ALL']&fields=page_name,page_id,ad_creative_bodies,ad_snapshot_url,spend,impressions,demographic_distribution&access_token=<YOUR_TOKEN>
In practice, you'd URL-encode this or use curl. Here's how it might look:
curl -G \ -d "search_terms=electric car" \ -d "ad_type=ALL" \ -d "ad_active_status=ALL" \ -d "ad_reached_countries=['ALL']" \ -d "fields=page_name,page_id,ad_creative_bodies,ad_snapshot_url,spend,impressions,demographic_distribution" \ -d "access_token=YOUR_ACCESS_TOKEN" \ "https://graph.facebook.com/v18.0/ads_archive"
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.For ads that have spend/impressions data (EU ads or political ads) you'd see something like
"spend": {"lower_bound": "100", "upper_bound": "499"} or "spend": "<100" depending on how they return the range.Pagination
If your query has many results, the API will only return a certain number per page. The default limit is 25 ads per response. You can increase this with the
limit parameter, up to a maximum of 2,000 ads in one request.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.It's a good idea to use filtering to avoid extremely large result sets. If you need to pull many thousands of records (say all political ads in the last election), you can page through in chunks of up to 2000.
Just be mindful of timeouts. Pulling the max 2000 might sometimes hit a timeout depending on server load, so sometimes a slightly smaller page size (like 500 or 1000) can be more reliable.
Also note: Meta might cap total results for certain queries. Anecdotally, queries can return tens of thousands of ads via pagination, but extremely broad queries might not be practical.
Handling "No Results"
If your query is too broad and outside the library scope, you might get an empty data set.
For example,
ad_reached_countries=['US']&ad_type=ALL without specifying political will return nothing (because non-political US ads aren't included).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:
• 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).
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?
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
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.
According to AdManage's calculator, launching 1,000 ads manually takes about 166.7 hours. With bulk launching capabilities, that becomes a fraction of the time.
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)
You need to test:
• 3 discount tiers × 5 creative variations × 2 formats (video/static) = 30 variations
• Across Facebook and Instagram
• Launch as paused for approval before going live
① Upload your 10 creative assets (5 concepts, each in video and static)
④ Set creative enhancement toggles per account
⑥ Use bulk preview links for team approvals
⑦ Go live once approved
Total time: About 30 minutes vs. 10+ hours manually.
Integration Opportunities
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
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's agency plan supports unlimited ad accounts. When you use the API to research across multiple client industries, you can quickly deploy insights across your portfolio.
Enterprise Teams with Compliance Needs
AdManage offers enterprise features including SSO/SAML, audit logs, and white-labeled reports. Combined with API-driven competitive research, this gives you both intelligence and governance.
Pricing That Makes Sense
Plan | Price (GBP) | Ad Accounts | Key Features |
In-House | £499/month | 3 accounts | Unlimited uploads, launches, team members, spend |
Agency | £999/month | Unlimited accounts | Everything in In-House + unlimited clients |
Enterprise | Custom | Unlimited | SSO/SAML, custom SLA, white-label reports, audit logs |
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 (2024-2025)
To ensure this guide is truly definitive, let's highlight recent developments up to 2025 that affect how you use the Ad Library API:
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. However, 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, up through late 2025, 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
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.
Can I see all competitor ads in any country?
No. The Ad Library API primarily shows:
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?
You don't. The API provides spend and impressions in ranges (e.g., "100-499", "1K-5K") for political/issue ads and EU/UK ads.
Exact figures aren't available. This is intentional (the library is about transparency, not giving away precise performance metrics).
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:
② 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?
The default limit is 25 ads per response. You can increase this with the
limit parameter, up to a maximum of 2,000 ads in one request.If there are more results, the JSON includes a
paging.next URL to retrieve the next batch.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?
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:
AdManage's fixed monthly pricing (£499 in-house, £999 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
② 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.
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.
Start your free trial of AdManage today and see how the combination of API-driven research + bulk execution transforms your advertising results.
Related Posts
How to Create Multiple Ads on Facebook (2025)
Learn how to create multiple Facebook ads fast. Compare manual, bulk upload, and automation tools that launch hundreds of ads in minutes.
Facebook Ads Not Delivering? How to Fix It (2025 Guide)
Is your Facebook ad not delivering? This guide breaks down the common causes, from budget issues to audience errors, and gives you actionable fixes.