Meta Ad Library API: Access, Limits and Example Requests (2026)

Want to pull ad data into a spreadsheet or script? Meta has an official Ad Library API, but its coverage is limited.

An ad being visible in the public library doesn't mean you can fetch it through the API.

Examples checked against Meta's API documentation on 17 September 2026. No authenticated test was run; the JSON output is illustrative.

What the official Meta API covers

Here are the two groups Meta currently documents:

1. Ads about social issues, elections or politics that were delivered anywhere in the world during the past seven years.
2. Ads of any type that were delivered to the UK or European Union during the past year.

The public Ad Library website has broader browsing use cases, including viewing active ads across Meta technologies. The API coverage rules above still apply to API requests, so an API query is not a general-purpose export of every commercial ad currently visible in the Ad Library.

You can request ad IDs, copy, advertiser Pages and delivery information. Spend and targeting fields depend on the ad type and region.

Just browsing? Start with the Facebook Ad Library guide.

How to request access

1. Use a Facebook account to confirm your identity and location. Meta says this confirmation follows the process required to run ads about social issues, elections or politics and may take a few days.
2. Create a Meta for Developers account and accept the applicable platform terms.
3. Create a Meta app, then use the Access the API flow on the official Ad Library API page.
4. Generate an access token for the app and include it with each Graph API request.

Meta requires an access token, but the public Ad Library API page does not promise one fixed token lifetime. Token validity depends on the token type and app configuration, and a token can expire or be revoked. Inspect the token with Meta's current developer tools instead of assuming it will remain valid for a fixed number of months.

Keep access tokens out of source control, screenshots and client-side JavaScript. The examples below use placeholders deliberately.

Make your first request

The endpoint is ads_archive. Replace <API_VERSION> with a supported Graph API version, including the v prefix, and <META_ACCESS_TOKEN> with your token.

Example 1: political ads delivered in the US

This request searches for political or issue ads containing “california” that reached the United States:

curl -G \
  --data-urlencode "search_terms=california" \
  --data-urlencode "ad_type=POLITICAL_AND_ISSUE_ADS" \
  --data-urlencode "ad_reached_countries=['US']" \
  --data-urlencode "fields=id,page_id,page_name,ad_snapshot_url,ad_creative_bodies,publisher_platforms,ad_delivery_start_time,ad_delivery_stop_time" \
  --data-urlencode "access_token=<META_ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/ads_archive"

Results appear in data, with paging for more pages. Here's an illustrative response:

{
  "data": [
    {
      "id": "1234567890",
      "page_id": "123456",
      "page_name": "Example Page",
      "publisher_platforms": ["FACEBOOK", "INSTAGRAM"],
      "ad_creative_bodies": ["Example ad copy"]
    }
  ],
  "paging": {
    "cursors": {
      "before": "CURSOR",
      "after": "CURSOR"
    },
    "next": "https://graph.facebook.com/<API_VERSION>/ads_archive?..."
  }
}

Example 2: commercial ads delivered in Germany

This searches for ads containing “shoes” that reached Germany:

curl -G \
  --data-urlencode "search_terms=shoes" \
  --data-urlencode "ad_type=ALL" \
  --data-urlencode "ad_reached_countries=['DE']" \
  --data-urlencode "ad_active_status=ALL" \
  --data-urlencode "fields=id,page_id,page_name,ad_creative_bodies,ad_snapshot_url" \
  --data-urlencode "access_token=<META_ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/ads_archive"

ALL covers ad type and status, but coverage limits still apply. Germany is the delivery country.

Start with these fields, then add more once the request works.

Read more than one page of results

Use the returned cursor to fetch more pages. This example requires Node.js 18+ and stops after five pages.

Set META_ACCESS_TOKEN and META_API_VERSION in your environment first. Save this as fetch-ads.js, then run node fetch-ads.js > ads.json.

async function fetchAds() {
  const token = process.env.META_ACCESS_TOKEN;
  const version = process.env.META_API_VERSION;

  if (!token || !version) {
    throw new Error('Set META_ACCESS_TOKEN and META_API_VERSION first.');
  }

  const endpoint = `https://graph.facebook.com/${version}/ads_archive`;
  const params = new URLSearchParams({
    search_terms: 'shoes',
    ad_type: 'ALL',
    ad_reached_countries: JSON.stringify(['DE']),
    ad_active_status: 'ALL',
    fields: 'id,page_id,page_name,ad_creative_bodies,ad_snapshot_url',
    access_token: token,
  });
  const ads = [];
  const maxPages = 5;
  let pagesRead = 0;
  let hasMore = true;

  while (hasMore && pagesRead < maxPages) {
    const response = await fetch(`${endpoint}?${params.toString()}`);
    const result = await response.json();

    if (!response.ok || result.error) {
      throw new Error('Meta request failed. Check token, access and fields.');
    }
    if (!Array.isArray(result.data)) {
      throw new Error('Meta returned an unexpected response.');
    }

    for (const ad of result.data) {
      ads.push(ad);
    }
    pagesRead += 1;
    hasMore = Boolean(result.paging && result.paging.next);

    if (hasMore) {
      const cursors = result.paging.cursors;
      if (!cursors || !cursors.after) {
        throw new Error('Next page exists, but its cursor is missing.');
      }
      params.set('after', cursors.after);
    }
  }

  console.log(JSON.stringify({ complete: !hasMore, pagesRead, ads }, null, 2));
}

fetchAds().catch(function (error) {
  console.error(error.message);
  process.exitCode = 1;
});

complete: false means more pages remain. Failed requests exit with an error. Add retries and rate-limit handling before increasing the page limit.

Snapshot URLs can contain tokens. Keep those exports private.

Quick plug: our Swipekit API gives you access to your saved ads using a workspace key.

Supported fields

The fields you can request depend on the ad type and where it was delivered.

Fields available for eligible ads

• id: the Ad Library ID.
• page_id and page_name: the Facebook Page associated with the ad.
• ad_creative_bodies, link titles, descriptions and captions: available creative text.
• ad_delivery_start_time and ad_delivery_stop_time: delivery dates in UTC.
• publisher_platforms: Meta technologies where the ad appeared, such as Facebook or Instagram.
• ad_snapshot_url: a link that displays the archived ad, including its uncompressed creative. Use and storage remain subject to Meta's terms.

Restricted transparency fields

• Political and issue ads may include spend and impression ranges, funding bylines, demographic distribution and regional delivery data.
• UK and EU ads may include estimated reach, targeting ages, gender and locations.
• EU ads may include beneficiary and payer information.
• Some Brazil fields apply only to political and issue ads delivered there.

Request only fields supported for the ad type and location you are querying. Meta may reject an incompatible field or return it without a value.

Restrictions and current limitations

• The official API does not provide unrestricted access to every commercial ad worldwide. Non-political ads must meet Meta's documented UK or EU delivery coverage.
• ad_reached_countries is required. Meta's overview includes UK and EU commercial ads, while its country-parameter note still refers to EU delivery. The commercial example above uses Germany; check a UK-only request against the current reference before relying on it.
• search_terms is limited to 100 characters. Use search_type to choose unordered keywords or an exact phrase.
• search_page_ids accepts up to ten Facebook Page IDs in one request.
• Media filters support ALL, IMAGE, MEME, VIDEO and NONE.
• The documented search parameters do not include a direct Ad Library ID filter. Use the supported search parameters and inspect the returned id values.
• A snapshot URL is not a bulk creative export. Meta says individual creative may be downloaded for analysis subject to its data-storage and platform terms.
• Results are paginated and availability can change when Meta changes API versions, field definitions or transparency requirements.

Common errors

The request returns an authentication error

Confirm that the access token is present, belongs to the correct app and remains valid. Generate or inspect tokens through Meta's current developer tooling; do not rely on an old token-lifetime assumption.

The request returns an authorization error

Complete identity and location confirmation, confirm the Meta developer account and app are configured, and use the Access the API flow. Access for one Facebook account or app should not be assumed to apply automatically to every other account or app.

The response is empty

Empty data array? Check these:

1. Coverage: commercial ads need UK/EU delivery to qualify.
2. Country: use the ad's delivery country.
3. Status: try ad_active_status=ALL to include inactive eligible ads.
4. Search: start with a simple term. search_page_ids takes Facebook Page IDs.
5. Filters: widen dates and remove extra filters, then add them back one at a time.

If the response contains an error, fix that first.

A field is missing or rejected

Many spend, reach, targeting and demographic fields are restricted by ad type or delivery location. Remove incompatible fields, confirm the ad's coverage and retry with the smallest working field list.

Only the first group of ads is returned

Read the paging object and follow the next cursor until there is no next page. Apply your own stopping and retry rules so a failed page does not silently truncate a large export.

Meta API versus Swipekit API

At a high level, Meta is the official API, but extremely limited. Swipekit is not official and only gives access to your own saved ads.

Use Meta's official API when your task fits its transparency coverage and fields. Use the Swipekit API when you need programmatic access to the research your team has already collected in Swipekit.

Ready to connect your saved research to an internal tool? Review the Swipekit Ad Library API documentation, create a workspace, and generate an API key from workspace settings.