In this article
Key takeaways
- The API returns ads about social issues, elections or politics in every country, and every ad delivered in the European Union.
- Commercial ads in Saudi Arabia and the Gulf are not available through the API, even though the web library shows them.
- Access requires a Meta developer account and identity confirmation, then an access token to call the ads_archive endpoint.
- For commercial ad data in the Gulf you need a tool that collects it from the public library, such as GccFY.
What is the Ad Library API?
An official Meta API that lets you search the Ad Library from your own code instead of a browser: you send search terms, countries and other filters, and get ads back as JSON, with fields such as the ad copy, the Page name, delivery start and stop dates, and platforms. Meta built it for transparency and research.
What does the API cover?
| Ad type | Web library | API |
|---|---|---|
| Social issue, election or political ads (all countries) | Yes, 7 years | Yes, with spend and reach |
| All ads delivered in the European Union | Yes, one year after last impression | Yes, with reach and audience data |
| Branded content (paid partnerships) | Yes | For authorised users |
| Commercial ads in the Gulf | Yes, active only | No |
In other words: a perfume store's ad in Riyadh shows up at facebook.com/ads/library, but the API will not return it. That gap is why tools like GccFY exist.
How to get access
- Create a developer account on Meta for Developers.
- Confirm your identity and location as Meta requires (this may involve an ID document).
- Create an app and generate an access token.
- Call the ads_archive endpoint of the Graph API with your search parameters.
An example request for ads in a European country (commercial ads outside Europe will not come back):
GET https://graph.facebook.com/v<version>/ads_archive
?search_terms=perfume
&ad_type=ALL
&ad_reached_countries=['FR']
&fields=page_name,ad_creative_bodies,ad_delivery_start_time,ad_snapshot_url,publisher_platforms
&access_token=<token>The key fields it returns
- page_name and page_id: the advertiser.
- ad_creative_bodies and ad_creative_link_titles: the copy and the link title.
- ad_delivery_start_time and ad_delivery_stop_time: the delivery period, from which you get running time.
- ad_snapshot_url: a link that renders the ad, instead of the image and video files.
- publisher_platforms and languages: platforms and languages.
- For political ads: spend and impression ranges, and their split by age, gender and region.
- For EU ads: total reach and its breakdown, targeting, and the beneficiary and payer.
Limits to know before you build on it
- No commercial ads outside Europe: the biggest limit for anyone working in the Gulf.
- No direct media files: you get a link that renders the ad, not the image or video file.
- Rate limits: each app has a request budget, and heavy use gets throttled.
- Tokens expire: access tokens have a lifetime and need renewing.
- Terms of use: Meta has terms on how this data may be used; read them before any commercial project.
An alternative for Gulf commercial ads
If your goal is to follow commercial ads in Saudi Arabia and the Gulf, the official API will not do. GccFY collects the Arabic ads of Gulf stores from the public library every day and keeps them after they stop, with running time, store platform and a snapshot of the landing page: 780,000+ ads from 69,000+ advertisers.
For specific data needs, contact us.
