Facebook Ad Library API · Endpoint

Facebook Ad Library Advertiser Ads API

Q: What do I send?

Send page_id. 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.advertiser-ads.list, checks its price and runs it with the same credits as the REST API.

List every ad of one advertiser's Facebook page, with the same filters as search.

1 credit per call
Failed calls are free
Updated 14 Oct 2026
fb-adlibrary.advertiser-ads.list

Start free, 100 credits API reference

Response completed

{  "total_items": 5,  "items": [    {      "ad_archive_id": "161966936869658",      "ad_id": null,      "collation_count": null,      "collation_id": null,      "contains_digital_created_media": false,      "contains_sensitive_content": false,      "currency": "",      "end_date": 1774854000,      "fev_info": null,      "gated_type": "ELIGIBLE",      "has_user_reported": false,      "hide_data_status": "NONE",      "is_aaa_eligible": true,      "is_active": false,      "page_id": "15087023444",      "page_is_deleted": false,      "page_name": "Nike",      "reach_estimate": null,      "report_count": null,      "spend": null,      "start_date": 1692082800,      "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": "{{product.name}}",        "caption": "nike.com/mx",        "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://ad.doubleclick.net/ddm/trackclk/N8893.2410306FACEBOOKADS/B30448992.373431644;dc_trk_aid=564542764;dc_trk_cid=196659869;dc_lat=;dc_r…",        "page_id": "15087023444",        "page_is_deleted": false,        "page_like_count": 39507015,        "page_name": "Nike",        "page_profile_uri": "https://www.facebook.com/nike/",        "root_reshared_post": null,        "body": {          "text": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis."        },        "cards": [          {            "title": "Calzado de entrenamiento para hombre Nike Metcon 8 - Gris",            "body": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis.",            "caption": "ad.doubleclick.net",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "",            "link_url": "https://www.nike.com/mx/t/calzado-de-entrenamiento-metcon-8-QHTl15?cp=77438547234_soc_",            "watermarked_resized_image_url": "",            "watermarked_video_hd_url": null,            "watermarked_video_sd_url": null,            "image_crops": []          },          {            "title": "Pantalones tejidos para hombre Nike Sportswear Tech Pack - Gris",            "body": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis.",            "caption": "ad.doubleclick.net",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "",            "link_url": "https://www.nike.com/mx/t/pantalones-tejidos-sportswear-tech-pack-dShS9G?cp=77438547234_soc_",            "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": [          "Sportswear",          "Product/service"        ],        "videos": []      },      "categories": [        "UNKNOWN"      ],      "menu_items": [],      "publisher_platform": [        "FACEBOOK",        "INSTAGRAM"      ],      "targeted_or_reached_countries": []    },    {      "ad_archive_id": "1568367420362553",      "ad_id": null,      "collation_count": null,      "collation_id": null,      "contains_digital_created_media": false,      "contains_sensitive_content": false,      "currency": "",      "end_date": 1774854000,      "fev_info": null,      "gated_type": "ELIGIBLE",      "has_user_reported": false,      "hide_data_status": "NONE",      "is_aaa_eligible": true,      "is_active": false,      "page_id": "15087023444",      "page_is_deleted": false,      "page_name": "Nike",      "reach_estimate": null,      "report_count": null,      "spend": null,      "start_date": 1692082800,      "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": "{{product.name}}",        "caption": "nike.com/mx",        "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://ad.doubleclick.net/ddm/trackclk/N8893.2410306FACEBOOKADS/B30448992.373431644;dc_trk_aid=564542764;dc_trk_cid=196659869;dc_lat=;dc_r…",        "page_id": "15087023444",        "page_is_deleted": false,        "page_like_count": 39507015,        "page_name": "Nike",        "page_profile_uri": "https://www.facebook.com/nike/",        "root_reshared_post": null,        "body": {          "text": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis."        },        "cards": [          {            "title": "Playera de skateboarding para hombre Nike SB - Negro",            "body": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis.",            "caption": "ad.doubleclick.net",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "",            "link_url": "https://www.nike.com/mx/t/playera-de-skateboarding-sb-QH417k?cp=77438547234_soc_",            "watermarked_resized_image_url": "",            "watermarked_video_hd_url": null,            "watermarked_video_sd_url": null,            "image_crops": []          },          {            "title": "Calzado de entrenamiento para hombre Nike Metcon 8 - Gris",            "body": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis.",            "caption": "ad.doubleclick.net",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "",            "link_url": "https://www.nike.com/mx/t/calzado-de-entrenamiento-metcon-8-QHTl15?cp=77438547234_soc_",            "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": [          "Sportswear",          "Product/service"        ],        "videos": []      },      "categories": [        "UNKNOWN"      ],      "menu_items": [],      "publisher_platform": [        "FACEBOOK",        "INSTAGRAM"      ],      "targeted_or_reached_countries": []    }  ]}

5 rows

#	Advertiser	Ad text	Button	Format	Started	Library ID	Contains digital created media	Contains sensitive content	End date
1	Nike	Entra a Nike.com y encuentra actualizaciones semanales de produ…	Shop now	DPA	1,692,082,800	161966936869658	false	false	1,774,854,000
2	Nike	Entra a Nike.com y encuentra actualizaciones semanales de produ…	Shop now	DPA	1,692,082,800	1568367420362553	false	false	1,774,854,000
3	Nike	Add a retro touch to any fit.	Shop now	IMAGE	1,777,446,000	1520310666349109	false	false	1,779,692,400
4	Nike	Add a retro touch to any fit.	Shop now	IMAGE	1,777,446,000	971292195762951	false	false	1,779,692,400
5	Nike	Add a retro touch to any fit.	Shop now	IMAGE	1,777,446,000	998660356025671	false	false	1,779,692,400

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
page_id	string	yes	The advertiser's numeric Facebook page ID, such as 15087023444 for Nike. Find it with the advertiser search.	15087023444
active	string	no	all, active (still running) or inactive.	all · active · inactive
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.	Nike
items[].snapshot.cta_text	string	The ad's button text.	Shop now
items[].snapshot.display_format	string	The ad's format, such as video or image.	DPA
items[].is_active	boolean	Whether the ad is running now.	false
items[].start_date	integer	When the ad started, as a Unix timestamp in seconds.	1,692,082,800
items[].ad_archive_id	string	Meta's ID for the ad in the Ad Library.	161966936869658
items[].snapshot.title	string	The ad's headline.	{{product.name}}
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.	nike.com/mx
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	null	How many versions of the ad Meta groups together.	null
items[].collation_id	null	The ID shared by versions of the same ad.	null
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,774,854,000
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.	true
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.	15087023444
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, AUDIENCE_NETWORK
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.	6 records
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.	SHOP_NOW
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.	empty in this sample
items[].snapshot.extra_texts	array	More text in the ad.	empty in this sample
items[].snapshot.extra_videos	array	More videos in the ad.	empty in this sample
items[].snapshot.is_reshared	boolean	Whether the ad reshares another post.	false
items[].snapshot.link_description	null	The text under the ad's link.	null
items[].snapshot.link_url	string	Where the ad's link goes.	https://ad.doubleclick.net/ddm/trackclk/N8893.2410306FACEBOOKAD…
items[].snapshot.page_categories	array	The page's categories.	Sportswear, Product/service
items[].snapshot.page_id	string	The ID of the Facebook page that runs the ad.	15087023444
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.	39,507,015
items[].snapshot.page_name	string	The page that runs the ad.	Nike
items[].snapshot.page_profile_uri	string	The page's address on Facebook.	https://www.facebook.com/nike/
items[].snapshot.root_reshared_post	null	The original post, when the ad reshares one.	null
items[].snapshot.videos	array	The ad's videos.	empty in this sample

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.advertiser-ads.list",  "input": {    "limit": 5,    "page_id": "15087023444"  }}'

import jsonimport osimport requestspayload = json.loads(r'''{  "capability": "fb-adlibrary.advertiser-ads.list",  "input": {    "limit": 5,    "page_id": "15087023444"  }}''')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.advertiser-ads.list",  "input": {    "limit": 5,    "page_id": "15087023444"  }}),});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

With Upscrape, list the ads of Nike's Facebook page (page ID 15087023444) in the Ad Library and tell me which platforms they ran on.

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

Facebook Ad Library

More from the Facebook Ad Library API

Same data, other platforms

The same data from other platforms

Questions

Facebook Ad Library Advertiser Ads API FAQ

The short answers. The docs have the long ones.

Still have a question? Talk to the people who build the endpoints.

Book a call [email protected]

How much does the Facebook Ad Library Advertiser Ads API cost?

1 credit per successful call, shown before it runs. You buy credits once, and paid credits never expire.

What do I send?

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

Do I need a Facebook Ad Library login?

No. It reads public Facebook Ad Library data; nothing runs on your account.

Can my AI agent call it?

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

Get started

Your first Facebook Ad Library call is free.

Up to 100 free credits to start, no card needed.

Start building for free Book a call