Facebook Ad Library API: Access, Queries and Limits

What the Ad Library API covers

The API is the programmatic version of the Meta Ad Library. Per the Ads Archive reference, reading it returns archived ads from the Meta Ad Library, searched by keyword across ad text, images, audio from video, and the call-to-action button.

You can search in two ways:

• By keyword. Pass a search_terms string. It is limited to 100 characters or less.
• By Page. Pass search_page_ids to request archived ads for up to 10 Facebook Page IDs at once.

You can also filter by ad status, delivery dates and countries, covered below.

One note on names: the Ad Library API is Meta's own endpoint. Some vendor tools also call their products an "ad library" or "ad library API". Those are different products. This guide covers Meta's.

What the API does not do

Read the limits before you plan a project around it.

• It does not translate searches. Meta says it does not translate your keyword searches, so you should write them in the language of the ads you are searching.
• Ads outside the EU may not appear. Meta's reference says ads that did not reach any location in the EU will only return if they are about social issues, elections or politics. Check this against the ads you expect to find, and use the Facebook Ad Library website to compare.
• Some filters are for political ads only. Meta lists bylines, delivery by region and estimated audience size filters as available only for POLITICAL_AND_ISSUE_ADS. The audience size filter accepts range boundaries from 1000 to 1000000.
• It searches ads. Meta's reference describes keyword search over the ad's text, images, video audio and button. Check the field list for your API version before you count on any other data.

How to get access

Every call needs a valid OAuth 2.0 access token. Without one, the API returns error code 190, which Meta's error table lists as "Invalid OAuth 2.0 Access Token." Meta's reference lists the access requirements, and they can change, so follow the current steps in the Ads Archive documentation instead of relying on a copy of them here.

Once you have a token, test it with the query in the next section.

A working query for ads_archive

The endpoint is ads_archive on the Graph API. Here is a query shape that uses the parameters Meta marks as important. Replace the version, token and terms with your own.

curl -G "https://graph.facebook.com/v27.0/ads_archive" \
  -d "search_terms=running shoes" \
  -d "ad_type=ALL" \
  -d "ad_reached_countries=['US']" \
  -d "ad_active_status=ACTIVE" \
  -d "access_token=YOUR_ACCESS_TOKEN"

What each parameter does:

• search_terms: the keywords, 100 characters or less, in the language of the ads.
• ad_type: Meta's reference marks this parameter as required. It takes ALL, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, HOUSING_ADS or POLITICAL_AND_ISSUE_ADS.
• ad_reached_countries: search ALL or pass ISO country codes to return ads that reached specific countries or locations.
• ad_active_status: defaults to ACTIVE, which covers all ads that are eligible for delivery. INACTIVE and ALL are the other options.
• access_token: your OAuth 2.0 token.

Treat the example as a starting point and check it against the reference for the API version you use, since Meta updates parameters between versions.

Narrow results by date and Page

• ad_delivery_date_min and ad_delivery_date_max use the format YYYY-mm-dd.
• search_page_ids takes up to 10 Facebook Page IDs in one request. This is how you pull the ads of a specific list of brands.

Special ad categories

The ad_type parameter narrows results to special ad categories: financial products and services, employment, housing, and political and issue ads. Meta notes that FINANCIAL_PRODUCTS_AND_SERVICES_ADS now replaces CREDIT_ADS, so update older code that still uses the old value.

Choosing the fields you get back

The API returns only the fields you ask for through the fields parameter, as other Graph API endpoints do. The list of available fields differs by version and ad type, so read the field list in Meta's reference for your version and request only what you need. Keep the field list small: it makes responses faster to read and easier to store.

Limits and errors to plan for

Meta's reference does not state a numeric rate limit, so build in retry logic with a back-off instead of a fixed request count.

Plan a competitor research run

A few habits keep an API project simple and within the limits above.

1. Start from a Page list. If you already know the brands you care about, collect their Facebook Page IDs and query them in groups of up to 10 with search_page_ids. This is cleaner than keyword searches, which can return ads from brands you have never heard of.
2. Search one idea per request. With a 100-character cap on search_terms, short specific terms work better than a sentence.
3. Run each language separately. Because keyword searches are not translated, a product term in English will not find ads written in Spanish. Repeat the search in each language you sell in.
4. Pick the right status. The default ACTIVE returns ads eligible for delivery. Switch to ALL when you want ads that have stopped running too, and use the delivery date filters to focus on a period.
5. Save what you pull. Store results with the date you ran the query, since the set of active ads changes from day to day.

If the output feels like more engineering than the question deserves, that is the sign to use the no-code route below.

Browse competitor ads without code

If you want to see what other brands are running and do not need a data pipeline, the API is more work than you need. Madgicx has an Madgicx ad library in the AI Ad Hub where you can browse other brands' ads and save the ones you like to inspiration boards. No access token and no code.

You can then turn a found ad into a new one. The AI Ad Generator can make image ads from any ad in the Meta Ad Library, ready to edit and use.

Use ads you find in your own Meta ads

A simple research loop looks like this:

1. Search a competitor or a keyword in the Ad Library.
2. Save the ads that run for a long time or appear in many versions into an inspiration board.
3. Note what they share: the hook, the offer, the format.
4. Generate your own image ads from those references, then test them against your current best ad.

Madgicx's AI Ad Generator handles the third and fourth steps, and you review everything before it runs.

Try Madgicx free for 7 days and browse the Ad Library

FAQ