Afina

Download app

AppleWindows
EN
BlogSocial Media

November 22, 2026

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

Collecting and organizing data from the Meta Ads Library

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, and run_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.

MethodBest useMain advantageKey limitation
manual reviewone-off analysis of 10-30 adsquick start and visual verificationdifficult to repeat consistently
Ad Library APIrecurring collection from a supported samplestructured JSON responses and cursor paginationaccess, regions, and fields are limited by Meta's rules
browser collectionauthorized scenario involving visible interface datacontrol over action sequence and screenshotsDOM changes, retries, and higher maintenance costs
prepared datasetanalysis of a large historical datasetquick connection to BI toolsdata 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.

Three methods for collecting Meta Ads Library data

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:

  1. define the research question and ad inclusion criteria
  2. record the source, country, category, status, and time range
  3. obtain authorized records through the interface, API, or approved browser automation
  4. save the original JSON response or HTML snapshot without changing values
  5. normalize dates to UTC, countries to ISO codes, and empty fields to null
  6. create a separate identifier for related creative groups to find close variations
  7. 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.

Facebook Ads Library data normalization workflow

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_key for a unique Library record
  • creative_family_id for 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.

Quality metrics for advertising data collection

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.

Browser automation limits and emergency stop controls

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.

CriterionAd Library APIBrowser automation
formatJSON with defined fieldsdata from the DOM, network responses, or screenshots
paginationpaging.next cursorinfinite scroll or a load button
stabilitydepends on API versions and policiesdepends on layout, locale, and page state
quality controlschema, statuses, and cursor logsselectors, screenshots, and DOM snapshots
maintenanceversion and token updatesselector, wait, and retry updates
best userecurring sample within official accessauthorized 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.

Download

FAQ — 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.

Related terms

Continue reading onWeb scraping automation — data processing | Afina Browser
Artem Vishnepolskyі

Artem Vyshnepolskyi is a drop hunting and Web3 automation specialist, active in the crypto industry since 2021 and a member of the Afina team. He focuses on systematic participation in testnets, campaigns, and retrodrop activities, with notable life-changing cases including Starknet, Movement, and Initia.

At Afina, he works as a Support Specialist, helping users implement automation solutions and adapt tools to their specific goals. With a humanities background and no formal technical education, Artem proves that effective Web3 automation is accessible even to non-technical users