Meta Ad Library API: what data you can get in 2026

What the official API returns

The Ad Library API is the ads_archive edge of Meta's Graph API. Meta describes it as covering "ads about social issues, elections or politics, as well as ads that deliver to the EU and associated territories."

Retention differs by type. Political and issue ads are "stored in the Ad Library for 7 years". EU ads are "archived for one year upon the delivery of their last impression."

Key parameters:

search_terms: up to 100 characters. Meta does not translate keywords.
ad_reached_countries: required. Country codes or ALL.
ad_type: POLITICAL_AND_ISSUE_ADS, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, HOUSING_ADS or ALL (default).

The endpoint is read-only. Fields depend on the ad's scope:

Scope	Fields
All returned ads	`id`, `page_id`, `page_name`, `ad_creation_time`, `ad_delivery_start_time`, `ad_delivery_stop_time`, `ad_creative_bodies`, `ad_creative_link_titles`, `ad_creative_link_captions`, `ad_creative_link_descriptions`, `ad_snapshot_url`, `publisher_platforms`, `languages`
Reach by location	`total_reach_by_location`: "Currently supported locations: EU, BR, and UK."
EU and UK ads	`age_country_gender_reach_breakdown`, `target_ages`, `target_gender`, `target_locations`
EU ads	`eu_total_reach`, `beneficiary_payers`
Political and issue ads	`bylines`, `currency`, `spend`, `impressions`, `estimated_audience_size`, `demographic_distribution`, `delivery_by_region`

What it doesn't return

NoteMeta's docs say: "Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics."

So a commercial ad that ran only in the US is outside the official API. spend and impressions are listed for political and issue ads only. The field list has no clicks or conversions.

Rate limits: the reference lists error 613, "Calls to this api have exceeded the rate limit." It gives no number.

Meta lists the access steps at https://www.facebook.com/ads/library/api/.

Other ways to get the data

Route	Data	Access	Price
Meta Ad Library API	Scope above, JSON via Graph API	Follow Meta's access steps	No fee listed on the reference page
Meta Ad Library website	Same library, searched in the browser	Open the site	No fee listed
ToolzerHub API	Public Ad Library search, ad details and advertiser pages as JSON	API key	1 credit per request; 50 free credits a month; $1.00 to $1.90 per 1,000 credits on packs
Apify Actors (general)	Depends on the Actor author	Apify account	Set by each Actor, check its page

Use Meta's API when you need its political or EU-only fields, such as eu_total_reach. Use a JSON route when you need ads outside that scope, for example a US commercial advertiser. Compared options: best Facebook Ad Library scrapers.

ToolzerHub endpoints

The docs list 8 operations under Meta Ads:

GET /v1/meta/search: ads by keyword (q required), with filters and cursor pagination
GET /v1/meta/page: ads from one page_id
GET /v1/meta/page-by-url: ads from a Page URL or username
GET /v1/meta/page-id: resolve a Page URL to a page_id
GET /v1/meta/ad-details: one ad, by ad_archive_id and page_id
GET /v1/meta/search-pages: advertiser pages by name
GET /v1/meta/filter-options: languages, pages and regions for a query
GET /v1/meta/resolve-url: turn a public Ad Library URL into API parameters

Example request

bash

curl "https://api.toolzerhub.com/v1/meta/search?q=running%20shoes&country=US" \
  -H "x-api-key: $TOOLZER_API_KEY"

Static API example, run 2026-10-07. The call returned 10 ads; one is shown and trimmed.

json

{
  "data": {
    "items": [{
      "ad_archive_id": "4259039927704549",
      "page_id": "20662169998",
      "page_name": "Saucony",
      "is_active": true,
      "start_date": 1771747200,
      "end_date": 1791356400,
      "publisher_platform": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER", "THREADS"],
      "spend": null,
      "reach_estimate": null,
      "snapshot": {
        "display_format": "DPA",
        "title": "{{product.name}}",
        "body": { "text": "The best of the best is all in one place. Shop our top shoes, running apparel, and retro staples." },
        "cta_type": "SHOP_NOW",
        "caption": "saucony.com"
      }
    }],
    "pageInfo": { "cursor": "AQHT...", "hasNextPage": true }
  }
}

Notes on this response:

spend and reach_estimate are null for this commercial ad.
title is {{product.name}} because it is a dynamic product ad (DPA). The response carries the unfilled template text.
start_date and end_date are Unix seconds.
Pass pageInfo.cursor as cursor to get the next page.

Not affiliated with Meta Platforms, Inc.

Sources

Meta Ad Library tools, https://transparency.meta.com/researchtools/ad-library-tools, checked 2026-10-07
Ad Library API reference (ads_archive), https://developers.facebook.com/docs/graph-api/reference/ads_archive/, checked 2026-10-07
ArchivedAd fields, https://developers.facebook.com/docs/graph-api/reference/archived-ad/, checked 2026-10-07
ToolzerHub Meta Ads reference, https://docs.toolzerhub.com/reference/meta-ads, checked 2026-10-07
ToolzerHub pricing and credit packs, https://toolzerhub.com/pricing, checked 2026-10-07
ToolzerHub credits, https://docs.toolzerhub.com/docs/credits, checked 2026-10-07

What the official API returns

What it doesn't return

Other ways to get the data

ToolzerHub endpoints

Example request

Sources

Query this from your own code

Related posts