Meta Ad Library API: what it returns, its limits and alternatives

What the Meta Ad Library API is

The Ad Library API is Meta's programmatic door into the Ad Library. It is one read-only Graph API endpoint, ads_archive, and Meta's developer reference says creating, updating and deleting are not supported. You send a search, you get back a list of archived ads.

Meta's Ad Library tools page describes its scope in one line: it supports analysis of social issue, election, political and EU-delivered ads, and authorized users can also analyze active, public branded content on Facebook and Instagram. That sentence is the whole story of why the API disappoints people who expected a way to pull a competitor's Facebook ads. It was built for transparency researchers and journalists, not for media buyers.

The facts below were read on 6 November 2026 from Meta's tools page and developer reference (see Sources). Where Meta's pages do not say something, this guide says so rather than guessing.

Which ads it returns

The ad_type parameter selects a category: ALL (the default), POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS and FINANCIAL_PRODUCTS_AND_SERVICES_ADS. Meta notes that the financial category replaces CREDIT_ADS.

Choosing ALL does not mean all ads, though. Meta's reference states that ads which did not reach any EU location are returned only if they concern social issues, elections or politics. Put together:

Our record of the API also lists the UK next to the EU, and Meta's field reference marks several fields as UK and EU. If the brand you watch sells in Europe, you will get something. If it sells only in North America, you will get almost nothing, even though the ads are visible on the website.

The ad_active_status filter defaults to ACTIVE, which returns only ads eligible for delivery. Pass ALL or INACTIVE to include ads that have stopped, which only helps for the categories Meta keeps (see below).

How to get access

Ad Library API: political and issue ads worldwide and ads delivered in the EU or UK, plus active public branded content for authorized users; needs an identity check and a developer app. In practice the steps are:

1. Confirm your identity with Meta. The API is limited to authorized users, and Meta's tools page does not describe the process, so start from the Ad Library API page linked under Sources.
2. Create a developer app at Meta for Developers, under the account that confirmed its identity.
3. Generate an access token for the app. A missing or expired token gives error 190 (invalid OAuth 2.0 access token), one of the error codes Meta lists.
4. Call ads_archive with at least ad_type and ad_reached_countries. The reference marks ad_type as required.

Meta's pages that we could read give no review time, fee or quota for these steps, so budget for it taking a while.

A first request

A request for active ads that mention a phrase, reaching the United States, in the political category, looks like this. The parameters are the ones in Meta's reference; replace VERSION and TOKEN with your own.

GET https://graph.facebook.com/VERSION/ads_archive
  ?ad_type=POLITICAL_AND_ISSUE_ADS
  &ad_reached_countries=US
  &search_terms=housing
  &ad_active_status=ALL
  &fields=id,page_name,ad_creative_bodies,ad_delivery_start_time,spend,impressions,ad_snapshot_url
  &access_token=TOKEN

Some details from the reference that save a first-day error:

• search_terms is at most 100 characters. A space acts as a logical AND. With search_type=KEYWORD_EXACT_PHRASE, separate several phrases with commas to require each.
• search_page_ids takes up to 10 Page IDs and returns archived ads for those Pages. This is the closest thing to "show me this brand's ads".
• Keyword searches are not translated: write them in the language of the ads.
• Results are paged; you have reached the end when data comes back empty.
• unmask_removed_content defaults to false. Set it to true and you can see content Meta removed for violating its standards.

What fields come back

Meta's ArchivedAd reference lists 28 fields. The ones you will care about, and where they apply:

Two things are missing from the list, and they are what most commercial users want. There is no field for clicks, conversions or cost per result, and there is no downloadable media file: the creative arrives as a snapshot URL you open, not as an image or video you store. The reference also says ad_creation_time is not the same as when the ad ran, so use the delivery start time.

Rate limits and other limits

Meta's reference gives an error code for going over: 613. It does not state an Ad Library API quota, and the Graph API rate-limiting page does not have an Ad Library section. It only says error 613 means a custom rate limit was reached and points back to the docs of the API being called.

What the Graph API rate-limiting page does state is the general app-level rule: calls within one hour equal 200 multiplied by the number of users. That is the platform rule for apps, and we found nothing Meta publishes that sets an Ad Library number on top of it. If you plan a scheduled job, read the current documentation and test with your own app, and build in a back-off on 613.

The limits you can read exactly:

• 100 characters in search_terms.
• 10 Page IDs in search_page_ids.
• Error codes: 613 rate limit, 100 invalid parameter, 190 invalid token.

Is it free? What it costs

The API has no price: Meta lists it as free. The cost is elsewhere.

• Your time. The identity check, the app and the token set-up come before the first useful call, and an integration needs someone to keep it running.
• The gap in the data. If your brands are US-only commercial advertisers, the free API returns nothing you can use, however well you build.
• No history for ordinary ads. The API cannot return what the library has dropped (7 years for political and issue ads, a year after the last impression for EU ads).

So the honest summary: free and official, right for researching political and EU advertising, and the wrong tool for most competitor research on ecommerce brands.

Which route fits your goal

• Research political or issue advertising, or EU ads with reach data. Use the Meta Ad Library API. Nothing else gives you Meta's own spend ranges and reach.
• Check what one brand runs today, without code. Use the Meta Ad Library website. Search the Page, filter to active ads.
• Track many ecommerce competitors on a schedule. The free route is a spreadsheet and a weekly check (the routine, step by step); the paid route is a tool that follows brands.
• Pull ordinary Facebook and Instagram ads into your own scripts or dashboards. A paid data API (below).
• Let Claude or ChatGPT research ads for you. An MCP server. Meta has none that we found.

Paid APIs and data tools that return ordinary ads

These are the tools that publish an API or an MCP server over a library of ordinary commercial ads. Each line is from the tool's own record, checked on 24 October 2026; prices are in the table on its compare page, not repeated here.

• AdLibrary: Business only: 1 credit per search, 100 requests a minute and 10,000 a day per key. A search returns the advertiser, ad text, button, platform, impressions, a heat score from 0 to 1,000, likes, shares, first seen, days running, countries, the preview and the landing page URL; it needs an app type (gaming, apps or e-commerce).
• AdPlexity: Yes, on every plan, sharing the 5,000 monthly credits with the MCP.
• Swipekit: Yes, on every plan: 2,000 API credits a month on Basic, 4,000 on Plus, 10,000 on Agency.
• Foreplay: Yes, credit-based (1 ad = 1 credit). Its API page includes 10,000 credits a month with every plan and trial; its pricing page lists AI tools (MCP or API) from Workflow. Extra packs from $99/mo.
• Atria: Yes: 1,200 REST calls a month on Core, unlimited from Plus.
• Spresh: Yes, on every plan: 10,000, 50,000 or 100,000 credits by plan; unlimited for $450/mo.
• Klipio: Yes, a developer API; ads export as CSV or JSON.
• AdLibrarySpy: Public JSON endpoints for stores and the weekly report (1,000 calls a day per IP), plus the MCP over HTTP.

Many price an API in credits, so the cost of a pull depends on how many ads you read. Compare how many ads one run reads, what each record includes and whether the tool keeps ads after they stop. Our AI-access comparison lines up MCP servers.

AdSwipeFile's API and MCP server instead

AdSwipeFile is a library of 63,244+ winning Facebook and Instagram ads, filed by brand, niche and format, and it is built to be read by software. Two ways in, one account:

• A JSON API. GET /api/v1/search, /api/v1/ads (filter by brand, niche, format, visual format, hook, season and offer type) and /api/v1/ads/ plus an ad id for one ad with a note on how its hook, format and offer are built. It needs an OAuth token or a signed-in session. Documented at the API docs, with an OpenAPI file for function-calling tools.
• An MCP server. Claude, ChatGPT and Cursor connect to it and search the library on your behalf. Setup is on the MCP page. The same token works for both.

What you get: ad creative, brand, niche, formats and standard tags, and the ad copy on any account. A list returns the newest 20 ads signed out and 50 on a free account, with the full list on paid plans.

What it costs: a free account includes 50 MCP/API calls for the life of the account. Pro ($39 a month) has a monthly allowance and Agency ($99) a larger one, each with a 7-day trial, and the API and MCP server share the allowance.

What it does not do, plainly: it holds library ads, not every ad on Meta, so it will not answer "what is this tiny brand running". It has no spend, reach or results, no Chrome extension, and Facebook and Instagram only. It complements the Meta API (which has the political and EU data) rather than replacing it.

Browse what is inside: by niche, Beauty, Fashion, Fitness and wellness, Food and drink, Pets, Home and garden, Apps and software, Jewelry and watches; by format, UGC selfie, Review, Before and after, Product image, Unboxing, Listicle, Text overlay, Us vs them; by brand, AG1, Glossier, Liquid Death, Warby Parker or all brands. Then ask your AI agent something like: "list the longest-running ads for pet food brands and write three hooks from them".

FAQ

Is the Meta Ad Library API free?

Yes, Meta lists it as free. You still need an identity check, a developer app and an access token, and it only returns political, issue and EU-delivered ads.

Does the Meta Ad Library API return commercial ads?

Only those delivered to the EU. Per Meta's reference, ads that did not reach an EU location are returned only if they concern social issues, elections or politics, so a US-only ecommerce ad is not returned.

What is the rate limit on the Meta Ad Library API?

Meta states error 613 for going over, but no Ad Library quota on the pages we read. The general Graph API rule for apps is calls in an hour equal 200 times the number of users.

Does the Meta Ad Library API show spend?

Spend and impressions come back as ranges, and only for social issue, election and political ads. Ordinary commercial ads have no spend field in the API.

What are alternatives to the Meta Ad Library API for Facebook ads?

Paid data APIs such as AdLibrary or AdPlexity, brand-tracking tools with an API such as Swipekit, and AdSwipeFile's JSON API and MCP server over its saved library. Compare the fields, coverage and whether ads are kept after they stop.

Is there an MCP server for the Meta Ad Library?

None from Meta that we found. Third-party tools offer MCP servers over their own ad data, and your AI agent can connect to AdSwipeFile's MCP server to search its library of Facebook and Instagram ads.

Can I download ad images and videos from the Meta Ad Library API?

Not as files. The API returns an ad snapshot URL that displays the archived ad, not a media file, so store the creative yourself or use a tool that does.

Sources

Checked on 6 November 2026 on each tool's own site. Prices are in US dollars as listed, and change: check the source before you buy. AdSwipeFile's facts come from its pricing page.

1. Meta Ad Library
2. Meta Ad Library API
3. Meta Ad Library tools
4. Graph API ads_archive reference
5. AdLibrary pricing
6. AdLibrary home page
7. AdLibrary API
8. AdLibrary agent skills
9. AdPlexity Social pricing
10. AdPlexity Social MCP
11. AdPlexity Social API
12. AdPlexity Social home page
13. AdPlexity pricing (all products)
14. AdPlexity home page
15. Swipekit pricing
16. Swipekit ad library MCP
17. Swipekit home page
18. Foreplay pricing
19. Foreplay MCP
20. Foreplay API
21. Foreplay home page
22. Foreplay mobile app
23. Atria pricing
24. Atria home page
25. Atria MCP
26. Atria MCP quickstart
27. Atria help: choose your plan
28. Atria help: start with the free plan
29. Meta Ad Library tools (transparency.meta.com)
30. Meta Ad Library API page
31. Graph API reference: ads_archive
32. Graph API reference: ArchivedAd fields
33. Graph API rate limiting (error 613 and the app-level rule)