What Is the Meta Ad Library API?

The Ad Library API lets software query the archive you can browse on the Ad Library website. Meta’s reference page for its ads_archive endpoint, written for Graph API v26.0 and checked on 2 Oct 2026, describes a search over archived ads. Meta also states that creating, updating or deleting is not possible on this endpoint, so it is for reading only.

What does Meta say the Ad Library API is?

Meta’s Ad Library help article calls it an application programming interface that enables a deeper analysis of social issue, electoral or political ads in the Ad Library, as well as ads that deliver to the EU and associated territories. For what the library itself shows and keeps, see what the Meta Ad Library is.

The same article says you can download Ad Library searches, but you must be logged in to Facebook and agree to the terms of service.

How does a search work?

Meta says a read returns archived ads from the Ad Library based on keyword searches of text, images, audio from video and the call-to-action button. Meta does not translate your keywords, so you should write them in the language of the ads.

Meta’s example request returns archived ads about social issues, elections and politics that contain the word “california” and reached an audience in the US:

curl -G \
-d "search_terms='california'" \
-d "ad_type=POLITICAL_AND_ISSUE_ADS" \
-d "ad_reached_countries=['US']" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/ads_archive"

Which search options can you use?

Parameter	What Meta says
search_terms	A blank space counts as a logical AND; the string is limited to 100 characters or less
search_type	KEYWORD_UNORDERED (the default) or KEYWORD_EXACT_PHRASE
search_page_ids	Up to ten Facebook Page IDs, separated by commas
ad_reached_countries	ALL or an ISO country code; ads that reached no EU location return only if they are about social issues, elections or politics
ad_active_status	ACTIVE (the default), INACTIVE or ALL
ad_delivery_date_min and ad_delivery_date_max	Dates in YYYY-mm-dd format, inclusive
ad_type	ALL (the default) or a special ad category such as HOUSING_ADS
languages, media_type, publisher_platforms	Filter by ad language, by image, meme or video, and by Meta technology
unmask_removed_content	Set to true to reveal content removed for violating Meta’s standards; the default is false

Which options work only for political ads?

Meta marks four parameters as available only for POLITICAL_AND_ISSUE_ADS: bylines (the “paid for by” disclaimer), delivery_by_region, estimated_audience_size_min and estimated_audience_size_max. For bylines, Meta says you must list the complete byline, so “Maria” would not return ads with the byline “Maria C. Lee for America”.

What comes back and what can go wrong?

Results arrive as JSON with data, a list of ArchivedAd nodes, and paging. Meta says that when data contains no values as you page through, you have reached the end of the results.

Meta’s reference lists five errors:

• 613: calls to this API have exceeded the rate limit.
• 100: invalid parameter.
• 2500: error parsing the graph query.
• 1009: failed to pass parameter validation.
• 190: invalid OAuth 2.0 access token.

How do you run a first search?

1. Build the path as https://graph.facebook.com/<VERSION>/ads_archive, naming a current version.
2. Add search_terms, or search_page_ids for specific Pages.
3. Set ad_reached_countries, as Meta’s example does.
4. Add ad_type if you want a special ad category.
5. Include your access_token and send the request.
6. Follow paging until data comes back empty.

FAQ

Can the API show what a competitor spends on ads?

Meta’s help article shows an amount spent, as a range, only for ads about social issues, elections or politics. It shows no spend for ordinary active ads. Check Meta’s ArchivedAd reference for the exact fields the API returns.

Does a search work across languages?

No. Meta says it does not translate keyword searches, so you should write the string in the language of the ads you want. If you are searching Spanish-language ads, Meta says to write your search string in Spanish.

Can you change or remove ads through this endpoint?

No. Meta’s reference says you can’t create, update or delete on this endpoint. It reads archived ads from the Ad Library. To change ads in your own account, you would use the Marketing API instead.