Marketing API Version

Ads Library

With the Ad Library API you perform keyword searches or search by Page ID for archived ads stored in the Ad Library. You can search data for all active and inactive ads related to politics or issues of importance. See Archived Ad and Facebook Ads Help Center, About ads related to politics or issues of national importance.

You can use the following fields in your query:

  • Date and time someone created the ad,
  • Start and end date when the ad ran,
  • Ad content, such as text, terms and disclaimers,
  • Ad creative, such as text and images, which you can access via a URL,
  • Currency used to pay for the ad,
  • Ad funding entity,
  • Page ID for the Facebook page that ran the ad, and
  • Ad performance data including total amount spent, as a range, total impressions ad received, as a range, demographic distribution, such as age, gender and location of people reached, as a percentage of total people reached.

Returns archived ads based keyword searches for text, image, audio from video and any call-to-action button in the ad. The API also returns archived ads for a given Facebook Page ID using the the following search parameter: search_page_ids= where you can provide up to ten page IDs.

Note that we do not translate keyword searches. If you search Spanish language ads you should provide a Spanish language search string.

Example

For instance, get archived ads related to politics or issues of national importance that contain the word california and which reached people 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"

We return a response as a JSON object:

{
 "data": [
 {
 "page_id": "123",
 "page_name": "123",
 "ad_snapshot_url": "https://www.facebook.com/ads/archive/render_ad/?id=123&access_token=ACCESS_TOKEN"
 },
 ],
 "paging": {
 "cursors": {
 "before": "MAZDZD",
 "after": "MAZDZD"
 },
 "next": "https://graph.facebook.com/VERSION/ads_archive?access_token=ACCESS_TOKEN&fields=page_id,page_name,ad_snapshot_url&search_terms='california'&ad_type=POLITICAL_AND_ISSUE_ADS&ad_reached_countries=['US']&limit=25&after=MAZDZD"
 }
}