Facebook API · Endpoint

Facebook Ads Library 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 facebook.ads-library.search, checks its price and runs it with the same credits as the REST API.

Search the public Ads Library by advertiser or keyword, by country and by active or ended ads.

1 credit per call
Failed calls are free
Updated 12 Oct 2026
facebook.ads-library.search

Start free, 100 credits API reference

Response completed

{  "summary": {    "total_items": 20  },  "items": [    {      "ad_archive_id": "1433408628182273",      "ad_id": null,      "collation_count": 1,      "collation_id": "2628619724001492",      "contains_digital_created_media": false,      "contains_sensitive_content": false,      "currency": "",      "end_date": 1785567600,      "fev_info": null,      "gated_type": "ELIGIBLE",      "has_user_reported": false,      "hide_data_status": "NONE",      "is_aaa_eligible": false,      "is_active": true,      "page_id": "222086361593149",      "page_is_deleted": false,      "page_name": "InfinitePay",      "reach_estimate": null,      "report_count": null,      "spend": null,      "start_date": 1771488000,      "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": null,        "caption": "www.infinitepay.io",        "additional_info": null,        "branded_content": null,        "byline": "",        "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": null,        "link_url": "https://www.infinitepay.io/tap",        "page_id": "222086361593149",        "page_is_deleted": false,        "page_like_count": 185907,        "page_name": "InfinitePay",        "page_profile_uri": "https://www.facebook.com/infinitepay/",        "root_reshared_post": null,        "body": {          "text": "Fazer R$500 em 2 horas vendendo na rua? :moneybag: Vem acompanhar um dia de vendas do Jair Brazza!\nQuem vende na rua sabe: tempo é dinheiro…"        },        "cards": [],        "ec_certificates": [],        "extra_images": [],        "extra_links": [],        "extra_texts": [],        "extra_videos": [],        "images": [],        "page_categories": [          "Product/service"        ],        "videos": [          {            "watermarked_video_hd_url": "",            "watermarked_video_sd_url": ""          }        ]      },      "categories": [        "UNKNOWN"      ],      "menu_items": [],      "publisher_platform": [        "FACEBOOK",        "INSTAGRAM"      ],      "targeted_or_reached_countries": []    },    {      "ad_archive_id": "2148393745715005",      "ad_id": null,      "collation_count": null,      "collation_id": null,      "contains_digital_created_media": false,      "contains_sensitive_content": false,      "currency": "",      "end_date": 1785567600,      "fev_info": null,      "gated_type": "ELIGIBLE",      "has_user_reported": false,      "hide_data_status": "NONE",      "is_aaa_eligible": false,      "is_active": true,      "page_id": "108824017345866",      "page_is_deleted": false,      "page_name": "Meta",      "reach_estimate": null,      "report_count": null,      "spend": null,      "start_date": 1781679600,      "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": "meta.com/ai-glasses/",        "additional_info": null,        "branded_content": 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.meta.com/ai-glasses/shop-all/",        "page_id": "108824017345866",        "page_is_deleted": false,        "page_like_count": 106635276,        "page_name": "Meta",        "page_profile_uri": "https://www.facebook.com/Meta/",        "root_reshared_post": null,        "body": {          "text": "From grocery runs to training for your next marathon, there’s a pair of AI glasses designed for you. Shop the collection now."        },        "cards": [          {            "title": "Wayfarer - Large - Matte Black - Gradient Graphite",            "body": "From grocery runs to training for your next marathon, there’s a pair of AI glasses designed for you. Shop the collection now.",            "caption": "meta.com",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "$247",            "link_url": "https://www.meta.com/ai-glasses/wayfarer-matte-black-graphite-polar-gradient",            "video_hd_url": null,            "video_preview_image_url": null,            "video_sd_url": null,            "watermarked_resized_image_url": "",            "watermarked_video_hd_url": null,            "watermarked_video_sd_url": null,            "image_crops": []          },          {            "title": "Wayfarer - Matte Black - Gradient Graphite",            "body": "From grocery runs to training for your next marathon, there’s a pair of AI glasses designed for you. Shop the collection now.",            "caption": "meta.com",            "cta_text": "Shop Now",            "cta_type": "SHOP_NOW",            "link_description": "$247",            "link_url": "https://www.meta.com/ai-glasses/wayfarer-matte-black-graphite-polar-gradient",            "video_hd_url": null,            "video_preview_image_url": null,            "video_sd_url": null,            "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": [],        "images": [],        "page_categories": [          "Company"        ],        "videos": []      },      "categories": [        "UNKNOWN"      ],      "menu_items": [],      "publisher_platform": [        "FACEBOOK",        "INSTAGRAM"      ],      "targeted_or_reached_countries": []    }  ]}

3 rows

#	Collation count	Contains digital created media	Contains sensitive content	End date	Gated type	Has user reported	Hide data status	Is aaa eligible	Is active
1	1	false	false	1,785,567,600	ELIGIBLE	false	NONE	false	true
2		false	false	1,785,567,600	ELIGIBLE	false	NONE	false	true
3	2	false	false	1,785,567,600	ELIGIBLE	false	NONE	true	true

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 advertiser's name or a keyword.	Meta AI
active_status	string	no	Active ads (the default), ended ads, or both.	active
country	string	no	Two-letter country code where the ads ran, or ALL.	US
limit	integer	no	How many ads to return.	20

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[].snapshot.title	null	The ad's headline, when it has one.	null
items[].snapshot.body	object	The ad's main text.	1 fields
items[].snapshot.caption	string	The link caption shown under the ad.	www.infinitepay.io
items[].ad_archive_id	string	The Ad Library's ID for the ad.	1433408628182273
items[].ad_id	null	A second ID for the ad, when the Ad Library gives one.	null
items[].categories	array	The Ad Library's categories for the ad.	UNKNOWN
items[].collation_count	integer	How many versions of this ad run together.	1
items[].collation_id	string	The ID shared by versions of the same ad.	2628619724001492
items[].contains_digital_created_media	boolean	Whether the ad is marked as containing digitally created media.	false
items[].contains_sensitive_content	boolean	Whether the ad is marked as sensitive.	false
items[].currency	string	The currency of the spend figures, when given.
items[].end_date	integer	When the ad stopped running, as a Unix time in seconds.	1,785,567,600
items[].fev_info	null	Extra details the Ad Library adds to some ads; usually empty.	null
items[].gated_type	string	Whether the Ad Library 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 the Ad Library hides any of the ad's data, such as NONE.	NONE
items[].impressions_with_index	object	Impression details, when the Ad Library gives them.	2 fields
items[].impressions_with_index.impressions_index	integer	The Ad Library's impressions band; -1 means not given.	-1
items[].impressions_with_index.impressions_text	null	Impressions as a range, when the Ad Library gives them.	null
items[].is_aaa_eligible	boolean	Meta's AAA eligibility flag for the ad.	false
items[].is_active	boolean	Whether the ad is running now.	true
items[].menu_items	array	Extra menu options shown with the ad; usually empty.	empty in this sample
items[].page_id	string	The Facebook page that runs the ad.	222086361593149
items[].page_is_deleted	boolean	Whether the page that ran the ad was deleted.	false
items[].page_name	string	The name of the page that runs the ad.	InfinitePay
items[].publisher_platform	array	Where the ad runs: Facebook, Instagram, Messenger and others.	FACEBOOK, INSTAGRAM, MESSENGER
items[].reach_estimate	null	Estimated reach, when the Ad Library 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 the Ad Library 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.byline	string	The byline shown on the ad, when it has one.
items[].snapshot.cards	array	The ad's carousel cards, when it has them.	empty in this sample
items[].snapshot.country_iso_code	null	The country code, when the Ad Library gives one.	null
items[].snapshot.cta_text	string	The button text on the ad.	Learn more
items[].snapshot.cta_type	string	The kind of button on the ad.	LEARN_MORE
items[].snapshot.disclaimer_label	null	The paid-for-by label, when the ad has one.	null
items[].snapshot.display_format	string	The ad's format, such as VIDEO.	VIDEO
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.images	array	The ad's images.	empty in this sample
items[].snapshot.is_reshared	boolean	Whether the ad reshares another post.	false
items[].snapshot.link_description	null	The link's description, when given.	null
items[].snapshot.link_url	string	Where the ad links to.	https://www.infinitepay.io/tap
items[].snapshot.page_categories	array	The categories of the page that runs the ad.	Product/service
items[].snapshot.page_id	string	The Facebook page that runs the ad.	222086361593149
items[].snapshot.page_is_deleted	boolean	Whether the page that ran the ad was deleted.	false
items[].snapshot.page_like_count	integer	Likes on the page that runs the ad.	185,907
items[].snapshot.page_name	string	The name of the page that runs the ad.	InfinitePay
items[].snapshot.page_profile_uri	string	Link to the page that runs the ad.	https://www.facebook.com/infinitepay/
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
items[].spend	null	Amount spent, when the Ad Library gives it.	null

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": "facebook.ads-library.search",  "input": {    "query": "Meta AI"  }}'

import jsonimport osimport requestspayload = json.loads(r'''{  "capability": "facebook.ads-library.search",  "input": {    "query": "Meta AI"  }}''')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": "facebook.ads-library.search",  "input": {    "query": "Meta AI"  }}),});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, get the Facebook ads library search for query "Meta AI". Tell me what it costs before you run it, then show the results as a table.

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

Facebook

More from the Facebook API

Questions

Facebook Ads Library Search 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 Ads Library Search 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 query. The input fields below list every option with its type and limits.

Do I need a Facebook login?

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

Can my AI agent call it?

Yes, over MCP: the agent finds facebook.ads-library.search, checks its price and runs it with the same credits as the REST API.

Get started

Your first Facebook call is free.

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

Start building for free Book a call