How to Access Meta Ad Library API (Step by Step)

Here is how to access the Meta Ad Library API: you confirm your identity with Meta, register as a Meta developer, create an app, generate an access token, and then call the Graph API ads_archive endpoint with a country and a search term. It's free, but it only returns ads about social issues, elections or politics, plus ads that reached the EU, so ordinary commercial ads from outside Europe won't come back.

I've set this up a few times for clients and for my own research. Below is the full sequence, a working example request, and the errors that trip most people up on day one.

Is the Meta Ad Library API free, and what does it actually return?

Yes, the API is free. There's no paid tier and no per-call charge. What you pay in is time: identity confirmation, app setup and token management.

The bigger question is scope. The API covers:

• Political and social-issue ads, in every country where Meta runs the Ad Library.
• All ads that reached the EU, commercial ones included, because of the Digital Services Act.

It does not cover a US-only skincare brand's ads, or an Indian D2C brand's ads that never ran in Europe. Those appear on the Ad Library website but not in the API. I cover the scope question in depth in what the Meta Ad Library API actually gives you. This post is about getting access and getting your first call to work.

What do you need before you start?

Have these ready before you open a single Meta settings page:

• A personal Facebook account in good standing, ideally one you've had for a while.
• A government-issued photo ID for identity confirmation.
• A phone that can receive a login code, since two-factor authentication is usually required for this flow.
• Some patience. Identity review is not always instant, and in some countries Meta has historically asked for an extra step such as a mailed code.

You do not need an ad account, a Business Manager or any ad spend. This is a transparency tool, not an advertising one.

How do you access the Meta Ad Library API step by step?

Here's the sequence I follow. Meta moves menus around often, so treat labels as approximate and look for the closest match at the time of writing.

1. 1
   Confirm your identityID check for social issue and political ads
2. 2
   Register as a Meta developerdevelopers.facebook.com with your Facebook login
3. 3
   Create an appAny basic app type works for Ad Library calls
4. 4
   Generate an access tokenGraph API Explorer, then extend it
5. 5
   Call ads_archiveCountry, search term, fields

Step 1: Confirm your identity

This is the step that holds most people up. Meta requires the same identity confirmation used for people who run ads about social issues, elections or politics. You typically start it from your Facebook account settings or from the Ad Library API page (facebook.com/ads/library/api), which links to the confirmation flow.

You'll upload a photo ID and confirm your country. Until this is approved, your app will not be allowed to call ads_archive, even with a valid token.

Approval can be quick or can take a few days. Do it first so the wait runs in the background while you set up everything else.

Step 2: Register as a Meta developer

Go to developers.facebook.com and log in with the same Facebook account you used for identity confirmation. Accept the developer terms and verify your account if prompted.

Using the same account matters. Your identity status is tied to the person, and the token you generate later carries that person's permissions.

Step 3: Create an app

From the developer dashboard, create a new app. Meta has reshuffled the app types several times, so pick the most basic option that lets you use the Graph API. You don't need to add Facebook Login, Marketing API or any other product for Ad Library calls.

Give it a clear name, add a contact email, and leave it in development mode. You're the only user, and that's fine.

Step 4: Generate an access token

The fastest route is the Graph API Explorer inside the developer site. Select your app, generate a user access token, and copy it.

That token is short-lived, usually around an hour or two. For anything beyond a quick test, exchange it for a long-lived token using your app ID and app secret. Long-lived user tokens last weeks rather than hours, but they still expire, so plan to refresh them.

Step 5: Call the ads_archive endpoint

Now the actual request. The ads_archive endpoint needs at least a country (ad_reached_countries) and either search_terms or search_page_ids.

What does a working ads_archive request look like?

Here's a minimal example for political and issue ads in the US. Swap in the current Graph API version, since Meta retires old versions on a regular schedule.

https://graph.facebook.com/vXX.X/ads_archive
  ?search_terms='climate'
  &ad_reached_countries=['US']
  &ad_type=POLITICAL_AND_ISSUE_ADS
  &ad_active_status=ACTIVE
  &fields=page_name,ad_creative_bodies,ad_delivery_start_time,ad_snapshot_url
  &limit=25
  &access_token=YOUR_ACCESS_TOKEN

Put it on one line when you run it. A few notes on the parameters:

To pull commercial ads that reached Europe, set ad_reached_countries to an EU country code such as ['DE'] or ['FR'] and use ad_type=ALL. That's the DSA route, and it's where the API is most useful to a media buyer.

Results come back as JSON with a paging object. Follow the next URL to get the following page, and keep going until there isn't one. If you'd rather script this than paste URLs, downloading Meta Ad Library data with Python walks through pagination and saving results to a file.

Why is my Ad Library API call failing?

Almost every problem I've seen falls into one of these buckets. Exact error codes and wording change, so match on the message as much as the number.

"Application does not have permission for this action." Usually means identity confirmation isn't complete, or you're using a token from a different account than the one that was confirmed. Check your confirmation status, then regenerate the token.

Invalid or expired token. Short-lived tokens die fast. Generate a fresh one, or set up the long-lived exchange properly.

Missing required parameter. ad_reached_countries is required. Country codes need to be in the array format shown above.

Empty data array. The call worked but nothing matched. Either the ads are out of scope (commercial, non-EU), the search term is too specific, or the ads are inactive and you filtered for active only.

Unsupported version. You copied an old tutorial with a retired Graph API version. Use the current one listed in Meta's developer docs.

Rate limiting. Heavy pagination in a tight loop will hit limits. Add a pause between calls and back off when you get throttled.

What can't you get from the API even with access?

This is where expectations usually break.

• No commercial ads outside the EU. Worth repeating, because it's the number one reason people give up.
• No media files. ad_snapshot_url is a link to view the rendered ad, not a video or image file.
• No exact spend. Where spend and impressions exist (political ads), they come as ranges.
• No engagement. Likes, comments and shares aren't returned for any ad.

The website still shows every active ad from any advertiser worldwide, including the "Started running on" date. For most competitor research, ad longevity on the website tells you more than anything the API returns. My Meta Ad Library guide covers how to read that signal.

What should you use if the API doesn't cover your competitors?

If your competitors are commercial brands outside the EU, the realistic options are the website itself, a tool built on top of it, or a paid database.

I compared the main routes in Facebook Ad Library API alternatives. The short version: for a handful of brands, working inside the Ad Library website is enough. The site has no download button, so I use our free extension, the Meta Ad Library downloader, which adds one to every ad and exports a whole search as a ZIP with a CSV of every ad. The manual method is in how to download Facebook Ad Library videos.

If you need niche-wide search across many advertisers, paid spy tools exist for that. BigSpy starts at $9 a month with a free tier, and AdSpy is $149 a month with no trial.

Whatever route you take, study the angle and the structure. Copy the angle, not the asset, and don't reuse another brand's creative commercially. This isn't legal advice.

FAQ

Is the Meta Ad Library API free?

Yes. There's no fee to use it, only the setup work of confirming your identity, creating a developer app and managing access tokens. The limit is scope, not price: it returns political and issue ads plus EU ads.

How long does Meta Ad Library API access take?

The app and token take minutes. Identity confirmation is the variable part and can take anywhere from a short wait to a few days, depending on your country and whether Meta asks for extra steps.

Why does the Ad Library API return no results for my competitor?

Most often because their ads are commercial and never reached the EU, so they're outside the API's scope. It can also be an overly specific search term or an active-only filter hiding inactive ads.

Do I need identity verification for the Facebook Ad Library API?

Yes. Meta requires the same identity confirmation used for social issue, election and political advertisers. Until it's approved, calls to ads_archive are refused even with a valid token.

Can the Meta Ad Library API download ad videos?

No. It returns text and metadata plus an ad_snapshot_url that opens the rendered ad in a browser. It doesn't hand you the video or image file, so saving creative needs a different method.