Facebook Ad Library API · Endpoint

Facebook Ad Library Ads Search API

Q: What do I send?

Send query. The input fields below list every option with its type and limits.

Q: Can my AI agent call it?

Yes, over MCP: the agent finds fb-adlibrary.ad.search, checks its price and runs it with the same credits as the REST API.

Search the Ad Library by keyword and get each ad's advertiser, text, button, format, platforms, status and run dates, with country, language, platform, media and date filters.

1 credit per call
Failed calls are free
Updated 14 Oct 2026
fb-adlibrary.ad.search

Start free, 100 credits API reference

Response completed

{  "total_items": 5,  "items": [    {      "ad_archive_id": "925321173274919",      "ad_id": null,      "collation_count": 2,      "collation_id": "1022906600523558",      "contains_digital_created_media": false,      "contains_sensitive_content": false,      "currency": "",      "end_date": 1791183600,      "fev_info": null,      "gated_type": "ELIGIBLE",      "has_user_reported": false,      "hide_data_status": "NONE",      "is_aaa_eligible": false,      "is_active": true,      "page_id": "89516513179",      "page_is_deleted": false,      "page_name": "Nordstrom Rack",      "reach_estimate": null,      "report_count": null,      "spend": null,      "start_date": 1785740400,      "state_media_run_label": null,      "total_active_time": null,      "impressions_with_index": {        "impressions_index": -1,        "impressions_text": null      },      "regional_regulation_data": {        "finserv": {          "is_deemed_finserv": false,          "is_limited_delivery": false        },        "tw_anti_scam": {          "is_limited_delivery": false        }      },      "snapshot": {        "title": "Fast & Free Pickup",        "caption": "Nordstromrack.com",        "additional_info": null,        "branded_content": null,        "brazil_tax_id": null,        "byline": null,        "country_iso_code": null,        "cta_text": "Learn more",        "cta_type": "LEARN_MORE",        "disclaimer_label": null,        "display_format": "VIDEO",        "event": null,        "is_reshared": false,        "link_description": "Fast & Free Pickup",        "link_url": "https://fb.com/canvas_doc/1072291375736811",        "page_id": "89516513179",        "page_is_deleted": false,        "page_like_count": 2518817,        "page_name": "Nordstrom Rack",        "page_profile_uri": "https://www.facebook.com/NordstromRack/",        "root_reshared_post": null,        "body": {          "text": "Buy online and pick up in store for free! Get up to 70% off Nike, Vince, Madewell, adidas and more."        },        "cards": [],        "ec_certificates": [],        "extra_images": [],        "extra_links": [          "https://stores.nordstromrack.com/search"        ],        "extra_texts": [],        "extra_videos": [          {}        ],        "page_categories": [          "Clothing (Brand)"        ],        "videos": [          {            "watermarked_video_hd_url": null,            "watermarked_video_sd_url": null          }        ]      },      "categories": [        "UNKNOWN"      ],      "menu_items": [],      "publisher_platform": [        "FACEBOOK",        "INSTAGRAM"      ],      "targeted_or_reached_countries": []    },    {      "ad_archive_id": "2087470841874320",      "ad_id": null,      "collation_count": null,      "collation_id": null,      "contains_digital_created_media": false,      "contains_sensitive_content": false,      "currency": "",      "end_date": 1791183600,      "fev_info": null,      "gated_type": "ELIGIBLE",      "has_user_reported": false,      "hide_data_status": "NONE",      "is_aaa_eligible": false,      "is_active": true,      "page_id": "67997232685",      "page_is_deleted": false,      "page_name": "Foot Locker",      "reach_estimate": null,      "report_count": null,      "spend": null,      "start_date": 1784703600,      "state_media_run_label": null,      "total_active_time": null,      "impressions_with_index": {        "impressions_index": -1,        "impressions_text": null      },      "regional_regulation_data": {        "finserv": {          "is_deemed_finserv": false,          "is_limited_delivery": false        },        "tw_anti_scam": {          "is_limited_delivery": false        }      },      "snapshot": {        "title": "Shop New Styles",        "caption": "footlocker.com",        "additional_info": null,        "branded_content": null,        "brazil_tax_id": null,        "byline": null,        "country_iso_code": null,        "cta_text": "Shop now",        "cta_type": "SHOP_NOW",        "disclaimer_label": null,        "display_format": "DPA",        "event": null,        "is_reshared": false,        "link_description": null,        "link_url": "https://www.footlocker.com/category/new-arrivals.html",        "page_id": "67997232685",        "page_is_deleted": false,        "page_like_count": 6728674,        "page_name": "Foot Locker",        "page_profile_uri": "https://www.facebook.com/Footlocker/",        "root_reshared_post": null,        "body": {          "text": "Refresh your wardrobe with new styles from Nike, New Balance, adidas, and more."        },        "cards": [          {            "title": "Shop New Styles",            "body": "Refresh your wardrobe with new styles from Nike, New Balance, adidas, and more.",            "caption": "footlocker.com",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "Shop the latest selection of New Arrivals at Foot Locker. Find the hottest sneaker drops from brands like Jordan, Nike, Under Armour, New B…",            "link_url": "https://www.footlocker.com/product/~/00D2VSLV.html?cm_mmc=Social%20Network-_-Facebook-_--_-Conversion-_--_--_-p-_--_-Evergreen%20Dynamic-_-…",            "watermarked_resized_image_url": "",            "watermarked_video_hd_url": null,            "watermarked_video_sd_url": null,            "image_crops": []          },          {            "title": "Shop New Styles",            "body": "Refresh your wardrobe with new styles from Nike, New Balance, adidas, and more.",            "caption": "footlocker.com",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "Shop the latest selection of New Arrivals at Foot Locker. Find the hottest sneaker drops from brands like Jordan, Nike, Under Armour, New B…",            "link_url": "https://www.footlocker.com/product/~/00051791.html?cm_mmc=Social%20Network-_-Facebook-_--_-Conversion-_--_--_-p-_--_-Evergreen%20Dynamic-_-…",            "watermarked_resized_image_url": "",            "watermarked_video_hd_url": null,            "watermarked_video_sd_url": null,            "image_crops": []          }        ],        "ec_certificates": [],        "extra_images": [],        "extra_links": [],        "extra_texts": [],        "extra_videos": [],        "page_categories": [          "Shopping"        ],        "videos": []      },      "categories": [        "UNKNOWN"      ],      "menu_items": [],      "publisher_platform": [        "FACEBOOK",        "INSTAGRAM"      ],      "targeted_or_reached_countries": []    }  ]}

5 rows

#	Advertiser	Ad text	Button	Format	Active	Started	Library ID	Contains digital created media	Contains sensitive content
1	Nordstrom Rack	Buy online and pick up in store for free! Get up to 70% off Nik…	Learn more	VIDEO	true	1,785,740,400	925321173274919	false	false
2	Foot Locker	Refresh your wardrobe with new styles from Nike, New Balance, a…	Shop now	DPA	true	1,784,703,600	2087470841874320	false	false
3	Perfect themes	🔥🍭Themepack is a FREE and personalized APP😍 various styles of T…	Install now	IMAGE	true	1,779,174,000	1550534860016399	false	false
4	Depop	Free Depop Shipping just dropped. Go find something you love.	Download	DPA	true	1,779,433,200	962050096457659	false	false
5	Nike	Run through summer with gear that can take the heat.	Shop now	DPA	true	1,788,246,000	1107386451952079	false	false

Try it live, free

Input

What you send

The input object of the request, with every field the endpoint accepts.

Field	Type	Required	What it does	Example
query	string	yes	The keyword or phrase to search for, such as nike.	nike
active	string	no	all, active (still running) or inactive.	active
country	string	no	A two-letter country code such as US, or ALL for worldwide.
cursor	string	no	Pass next_cursor from the last response to get the next page.
end_date	string	no	Only ads shown on or before this day (YYYY-MM-DD).
languages	array<string>	no	Only ads in these languages, such as ["en", "es"].
limit	integer	no	How many ads to return in this call.	5
media_type	string	no	Only ads with this media: image, video, meme or none. all by default.	all · image · video · meme · none
platforms	array<string>	no	Only ads shown on these platforms, such as ["instagram"] or ["facebook"].	facebook · instagram · messenger · audience_net…
sort_by	string	no	The order: impressions, relevance or date.	impressions · relevance · date
start_date	string	no	Only ads shown on or after this day (YYYY-MM-DD).

Response

Fields it returns

What each record in the response holds, with the values from the sample above.

Field	Type	What it is	Example
items[].page_name	string	The page that runs the ad.	Nordstrom Rack
items[].snapshot.cta_text	string	The ad's button text.	Learn more
items[].snapshot.display_format	string	The ad's format, such as video or image.	VIDEO
items[].is_active	boolean	Whether the ad is running now.	true
items[].start_date	integer	When the ad started, as a Unix timestamp in seconds.	1,785,740,400
items[].ad_archive_id	string	Meta's ID for the ad in the Ad Library.	925321173274919
items[].snapshot.title	string	The ad's headline.	Fast & Free Pickup
items[].snapshot.body	object	The ad's main text.	1 fields
items[].snapshot.caption	string	The site the ad links to, as it is shown.	Nordstromrack.com
items[].ad_id	null	A second ID for the ad, when Meta gives one.	null
items[].categories	array	Meta's categories for the ad.	UNKNOWN
items[].collation_count	integer	How many versions of the ad Meta groups together.	2
items[].collation_id	string	The ID shared by versions of the same ad.	1022906600523558
items[].contains_digital_created_media	boolean	Whether the ad says it uses digitally created media.	false
items[].contains_sensitive_content	boolean	Whether Meta marks the ad as sensitive.	false
items[].currency	string	The currency of the spend figures, when shown.
items[].end_date	integer	When the ad stopped, as a Unix timestamp in seconds.	1,791,183,600
items[].fev_info	null	Extra details Meta adds to some ads; usually empty.	null
items[].gated_type	string	Whether Meta shows the ad openly, such as ELIGIBLE.	ELIGIBLE
items[].has_user_reported	boolean	Whether the viewer reported the ad; always false here.	false
items[].hide_data_status	string	Whether Meta hides any of the ad's data, such as NONE.	NONE
items[].impressions_with_index	object	Impression details, when Meta gives them.	2 fields
items[].impressions_with_index.impressions_index	integer	Meta's impressions band; -1 means not given.	-1
items[].impressions_with_index.impressions_text	null	Impressions as a range, when Meta gives them.	null
items[].is_aaa_eligible	boolean	Meta's AAA eligibility flag for the ad.	false
items[].menu_items	array	Extra menu options shown with the ad; usually empty.	empty in this sample
items[].page_id	string	The ID of the Facebook page that runs the ad.	89516513179
items[].page_is_deleted	boolean	Whether the page has been removed.	false
items[].publisher_platform	array	Where the ad runs, such as Facebook or Instagram.	FACEBOOK, INSTAGRAM, MESSENGER
items[].reach_estimate	null	Estimated reach, when Meta gives it.	null
items[].regional_regulation_data	object	Whether regional rules limit where the ad is shown.	2 fields
items[].regional_regulation_data.finserv	object	Whether the ad counts as financial services and is limited for it.	2 fields
items[].regional_regulation_data.tw_anti_scam	object	Whether Taiwan's anti-scam rules limit where the ad is shown.	1 fields
items[].report_count	null	How many times the ad was reported, when Meta gives it.	null
items[].snapshot	object	The ad as people see it.	30 fields
items[].snapshot.additional_info	null	Extra information shown on the ad, when it has some.	null
items[].snapshot.branded_content	null	Paid partnership details, when the ad is branded content.	null
items[].snapshot.brazil_tax_id	null	Always empty: personal tax IDs are left out.	null
items[].snapshot.byline	null	The byline shown on the ad, when it has one.	null
items[].snapshot.cards	array	The cards of a carousel ad.	empty in this sample
items[].snapshot.country_iso_code	null	The country code, when Meta gives one.	null
items[].snapshot.cta_type	string	The kind of button, such as Learn more.	LEARN_MORE
items[].snapshot.disclaimer_label	null	The paid-for-by label, when the ad has one.	null
items[].snapshot.ec_certificates	array	Certificates shown with the ad, when it has any.	empty in this sample
items[].snapshot.event	null	The event the ad promotes, when it has one.	null
items[].snapshot.extra_images	array	More images in the ad.	empty in this sample
items[].snapshot.extra_links	array	More links in the ad.	https://stores.nordstromrack.com/search
items[].snapshot.extra_texts	array	More text in the ad.	empty in this sample
items[].snapshot.extra_videos	array	More videos in the ad.	1 records
items[].snapshot.is_reshared	boolean	Whether the ad reshares another post.	false
items[].snapshot.link_description	string	The text under the ad's link.	Fast & Free Pickup
items[].snapshot.link_url	string	Where the ad's link goes.	https://fb.com/canvas_doc/1072291375736811
items[].snapshot.page_categories	array	The page's categories.	Clothing (Brand)
items[].snapshot.page_id	string	The ID of the Facebook page that runs the ad.	89516513179
items[].snapshot.page_is_deleted	boolean	Whether the page has been removed.	false
items[].snapshot.page_like_count	integer	How many likes the page has.	2,518,817
items[].snapshot.page_name	string	The page that runs the ad.	Nordstrom Rack
items[].snapshot.page_profile_uri	string	The page's address on Facebook.	https://www.facebook.com/NordstromRack/
items[].snapshot.root_reshared_post	null	The original post, when the ad reshares one.	null
items[].snapshot.videos	array	The ad's videos.	1 records

REST API · MCP server

Call it from your code, or ask your agent

Set UPSCRAPE_API_KEY to your key and copy a working request.

curl --request POST \  --url https://data.upscrape.com/execute \  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \  --header "Content-Type: application/json" \  --header "Prefer: wait=30" \  --data '{  "capability": "fb-adlibrary.ad.search",  "input": {    "active": "active",    "limit": 5,    "query": "nike"  }}'

import jsonimport osimport requestspayload = json.loads(r'''{  "capability": "fb-adlibrary.ad.search",  "input": {    "active": "active",    "limit": 5,    "query": "nike"  }}''')response = requests.post(    "https://data.upscrape.com/execute",    headers={        "Authorization": f"Bearer {os.environ['UPSCRAPE_API_KEY']}",        "Content-Type": "application/json",        "Prefer": "wait=30",    },    json=payload,)response.raise_for_status()print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data.upscrape.com/execute", {  method: "POST",  headers: {    "Authorization": `Bearer ${process.env.UPSCRAPE_API_KEY}`,    "Content-Type": "application/json",    "Prefer": "wait=30",  },  body: JSON.stringify({  "capability": "fb-adlibrary.ad.search",  "input": {    "active": "active",    "limit": 5,    "query": "nike"  }}),});if (!response.ok) {  throw new Error(`Upscrape request failed: ${response.status}`);}console.log(JSON.stringify(await response.json(), null, 2));

In your AI agent Claude · Cursor · any MCP client

1Add the Upscrape MCP server

https://data.upscrape.com/mcp

2Ask for the data in plain words

Using Upscrape, search the Facebook Ad Library for active ads mentioning nike and show me five with the advertiser, the ad text, the button and when each started.

The agent finds the endpoint, shows you the price, and runs it with your credits.

Facebook Ad Library