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

The official Meta Ad Library API lets approved developers query Meta's transparency archive. Its coverage depends on the ad type and delivery location: political and issue ads are available worldwide for seven years, while ads of any type are available when they were delivered to the UK or European Union during the past year.

This guide was technically reviewed against Meta's current Ad Library API documentation on 22 July 2026.

Contents

• What the official Meta API covers
• How to request access
• Make your first request
• Supported fields
• Restrictions and current limitations
• Common errors
• Meta API versus Swipekit API

What the official Meta API covers

Meta documents two primary groups of ads that can be queried through the API:

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.

For eligible ads, the official API can return the Library ID, creative text, Page name and Page ID, delivery dates and the Meta technologies where the ad appeared. Additional spend, impression, demographic, targeting, beneficiary and payer fields are limited to the ad types and regions specified in Meta's field documentation.

How to request access

Meta currently documents this access process:

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 official endpoint is ads_archive on the versioned Graph API. This request searches for political or issue ads containing “california” that reached the United States:

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

If you need structured access to ad research already saved across supported sources, use Swipekit's multi-platform Ad Library API. It is a separate Swipekit service and does not replace or impersonate Meta's official API.

A successful Meta response contains a data array and, when more results are available, a paging object:

{
  "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?..."
  }
}

Follow paging.next or the returned cursor instead of assuming one response contains the complete result set.

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. Ads that did not reach the EU return only when they are about social issues, elections or politics.
• 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

Check the coverage rules first. A normal commercial ad outside the UK and EU will not become eligible merely because its country was included in the query. Also check dates, active status, search terms and ad_type.

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

The two APIs solve different problems and use separate authentication.

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.