Facebook Ads Library: data collection, API, and creative research automation

Facebook Ads Library is an open database of Meta ads that helps researchers study ad creatives, offers, and advertiser activity. It shows which ads an advertiser has launched, but it does not prove that those ads are profitable. For broader idea research, it helps to first understand how a spy tool helps find creatives, then separate observable facts from hypotheses. Run duration, the number of variations, or repeated use of the same hook can serve as signals. However, none of them reveals CPA, ROAS, or exact ad spend.
The right workflow depends on scale. For a one-off analysis of ten ads, manual saving is usually easiest. Hundreds of records across several countries already require a data schema, stable identifiers, and a run log. This is where marketing research turns a folder of screenshots into a reproducible process with a defined sample.
Choose the technical method only after defining the research goal. If you need officially available structured fields, check the Ad Library API. For a small visual review, use the interface. Browser-based data scraping is appropriate only for an authorized scenario that the API cannot cover, and it requires separate quality controls.
What data is available in the Meta Ads Library
The Meta Ads Library provides public context for an ad: Library ID, advertiser Page, status, delivery dates, placement platforms, and available creative elements. The field set varies by ad category, region, and access method. A schema that makes every column mandatory can therefore become unusable very quickly.
For commercial ads, the public interface usually displays the text, headline, format, action button, start date, and Meta placements. Some fields may be empty or contain several variations. A carousel, for example, can include multiple texts and headlines in one record.
The official API has clearer boundaries. Meta describes global access to seven years of political and social issue ads, as well as ads of various types shown in the United Kingdom or the EU over the past year. For ordinary commercial ads outside those limits, the Library interface may show more than the API available to a particular researcher returns.
Do not mix published data with analytical conclusions. Your database should distinguish between these groups:
- original Meta fields without edits
- normalized values used for filtering and matching
- team annotations, such as hook, offer, or proof type
- collection metadata, including
collected_at,query_id, andrun_id
Store null in the factual data table when a value has not been published. Zero means that the value is actually zero, while null means the data is unavailable. That distinction is critical in reporting.
When to use the official API, exports, or browser collection
Choose the official API for repeatable queries within supported categories and regions. Manual collection works for a small sample, while browser automation is needed only when an authorized process depends on visible page elements that are absent from the API response.
| Method | Best use | Main advantage | Key limitation |
|---|---|---|---|
| manual review | one-off analysis of 10-30 ads | quick start and visual verification | difficult to repeat consistently |
| Ad Library API | recurring collection from a supported sample | structured JSON responses and cursor pagination | access, regions, and fields are limited by Meta's rules |
| browser collection | authorized scenario involving visible interface data | control over action sequence and screenshots | DOM changes, retries, and higher maintenance costs |
| prepared dataset | analysis of a large historical dataset | quick connection to BI tools | data origin and freshness must be verified |
For API work, record the Graph API version, request parameters, countries, time range, and fields list. Follow the paging.next cursor for as long as it exists instead of incrementing a page number manually. This reduces the risk of missing data because of a mistaken assumption about pagination.

If the interface or API does not return exact budget, CPA, or conversion data, do not fill those columns with assumptions presented as facts. You can add a separate analyst_hypothesis field, but it should never enter the raw data layer.
How to build an ad data collection and normalization workflow
A reliable process begins with the question the final report must answer. A request to "collect competitors' ads" is too broad. A request to "find new hooks in videos from five German brands over the past seven days" immediately defines the country, period, advertisers, and creative type.
For repeatable collection, follow these steps:
- define the research question and ad inclusion criteria
- record the source, country, category, status, and time range
- obtain authorized records through the interface, API, or approved browser automation
- save the original JSON response or HTML snapshot without changing values
- normalize dates to UTC, countries to ISO codes, and empty fields to
null - create a separate identifier for related creative groups to find close variations
- manually review the sample and record collection quality metrics
A minimal table can include ad_library_id, page_id, page_name, start_time, stop_time, status, publisher_platforms, creative_body, headline, destination_domain, snapshot_url, collected_at, and run_id. For creative analysis, add format, hook, offer, cta, and creative_family_id, but mark them as derived fields.

Keeping everything in one CSV is convenient only at the beginning. Once runs become frequent, dedicated data management for automated workflows makes it easier to compare states, validate types, and repeat analyses. The original data remains unchanged, so after correcting normalization rules, you can process it again without returning to the source.
How to verify pagination, completeness, and duplicate records
Collection validation must answer three questions: were all available pages processed, did any fields disappear, and how many records are duplicates? One large CSV without a run log cannot answer any of them reliably.
For cursor pagination, store the request number, returned cursor, HTTP status, record count, and response time. End the loop only when paging.next is absent or a documented stopping condition is met. If an empty response appears midway through the loop, log the error and retry after a delay. Do not silently skip it.
Deduplicating only by ad_library_id removes exact copies but does not merge variations of the same creative. For creative analysis, add a hash made from normalized text, headline, destination domain, and media link. This provides two levels:
record_keyfor a unique Library recordcreative_family_idfor a group of related creatives
Calculate four metrics after every run. completeness_rate shows the share of records with all required fields filled. duplicate_ratio measures the share of exact duplicates. Calculate field_fill_rate separately for unstable fields such as the headline or destination URL. change_rate shows the share of new, changed, and no longer visible records relative to the previous run.

A sharp drop in field_fill_rate almost always calls for checking the parser or API response. A sudden rise in the number of ads may be real, but first verify the country, status, time range, and Page ID. Page names can change or coincide, so Page ID is more reliable than a text search for the brand.
For recurring local monitoring, compare records together with the run conditions. The guide to local market research explains why geographic settings and a stable work environment affect reproducibility. Mark a missing ad as "no longer observed" until another source confirms that it was stopped or removed.
What tools are needed to automate creative research
An API workflow needs an HTTP client, scheduler, raw-response storage, and normalization table. A dynamic interface requires Playwright, Puppeteer, or Selenium, but maintaining selectors, wait logic, and checks usually takes more time than writing the first script.
The toolset can be divided by purpose:
- an HTTP client or SDK for Graph API requests
- Playwright or Puppeteer for authorized browser workflows
- PostgreSQL, BigQuery, or another store with a stable schema
- a scheduler for recurring runs and controlled retries
- a BI dashboard for tracking changes in hooks, formats, offers, and calls to action (CTA)
- an error log that flags empty responses or structural changes
Do not run browser automation without defined limits. Set a maximum page count, overall timeout, retry count, and concurrency limit. The script should stop if a selector disappears or the share of empty fields exceeds a threshold. This reduces the risk of collecting thousands of faulty records that later need repair.

A language model can handle part of the creative classification. Give it a fixed category list, an uncertain field, and a requirement to return structured JSON. Then review a random sample from every run. The model can group hooks and offers, but it does not know the ads' actual performance and should not invent explanations for an advertiser's decisions.
How the API differs from browser automation
The API returns documented structured fields, whereas browser automation extracts data from a user-facing interface. As a result, the API is easier to test and maintain. A browser workflow is more flexible with visible content but depends more heavily on the DOM, JavaScript loading, and session state.
| Criterion | Ad Library API | Browser automation |
|---|---|---|
| format | JSON with defined fields | data from the DOM, network responses, or screenshots |
| pagination | paging.next cursor | infinite scroll or a load button |
| stability | depends on API versions and policies | depends on layout, locale, and page state |
| quality control | schema, statuses, and cursor logs | selectors, screenshots, and DOM snapshots |
| maintenance | version and token updates | selector, wait, and retry updates |
| best use | recurring sample within official access | authorized task with visible data beyond API capabilities |
You do not have to choose only one method. The API can build the main record set, while a browser test checks a small control sample in the interface. This approach provides structured data and helps reveal differences between the response and what an analyst sees.
How to isolate research sessions and assess process limitations
Isolation helps reproduce working conditions, but it must not be used to conceal prohibited actions. A separate profile keeps cookies, localStorage, language, time zone, and proxy settings together. This helps separate work for different clients, markets, and test sessions within one browser.
The practical setup for a team is simple. Assign each profile to a market or client, store request parameters alongside run_id, restrict roles, and do not use employees' personal sessions. This material is provided for informational and educational purposes only.
Afina can organize this workflow: isolated profiles preserve research session state, while the local API can launch a profile and connect Playwright or Puppeteer through CDP. A detailed setup is available in the guide to the Afina API for REST automation. This does not expand access to Meta data or override its rules. The tool only helps organize an authorized process, event logs, and run environments.
DownloadFAQ — Frequently Asked Questions
What is the Facebook Ads Library?
Facebook Ads Library is a public database of ads shown across Meta products. It lets users view creatives, advertiser Pages, dates, and available delivery parameters.
Can Facebook Ads Library data be collected without logging in?
Part of the public Library is available without logging in. Access depends on the region, ad category, and Meta's current rules.
Does Meta provide an official Ads Library API?
Yes. Meta provides the Ad Library API for specific categories, regions, and periods. Access requires an account, authorization, and a Meta for Developers app.
What data does the Ad Library API return?
The API may return Library ID, Page ID, Page name, delivery dates, platforms, and available creative elements. Additional fields depend on the ad type and region.
Does the Ads Library show exact budget and ROAS?
No. Exact budget, CPA, conversions, and ROAS are generally unavailable for ordinary commercial ads. These metrics cannot be inferred from a creative's run duration alone.
How should duplicate ads be removed?
Remove exact duplicates by Library ID, and group close variations using a hash of the text, headline, domain, and media. Keep the two keys separate.
Which is better for data collection, the API or Playwright?
The API is better for repeatable structured samples within official access. Playwright is suitable for an authorized browser process that the API does not cover.
How can ad collection completeness be verified?
Keep a cursor pagination log, record counts per page, and required-field fill rates. Sharp changes in these metrics should stop the process and trigger a manual review.
