FACEBOOK AD LIBRARY API
Search
Retrieve search from Facebook Ad Library with a single API request.
GET
/api/data/v1/facebook/adLibrary/search/ads1credit base cost
Request parameters
Up to 1 creditKeyword to search for
Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
If you want to search by exact phrase or not
Search for all ads or only political and issue ads
This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR.
Status of the ad. Defaults to ACTIVE.
Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.
Impressions start date. Needs to be in YYYY-MM-DD format.
Impressions end date. Needs to be in YYYY-MM-DD format.
Cursor to paginate through results
Set to true for a trimmed down version of the response
Live requests use your prepaid balance. Cached responses cost zero where supported.
curl --request GET \
--url 'https://fetchgoblin.com/api/data/v1/facebook/adLibrary/search/ads?query=running' \
--header 'x-api-key: YOUR_FETCHGOBLIN_API_KEY'Response
Example{
"success": true,
"searchResults": [
{
"ad_archive_id": "1378176106734781",
"end_date": 1747638000,
"is_aaa_eligible": false,
"is_active": true,
"page_id": "119749581219299",
"page_name": "Makhumalo",
"political_countries": [],
"reach_estimate": null,
"snapshot": {
"branded_content": null,
"page_id": "119749581219299",
"page_is_deleted": false,
"page_profile_uri": "https://www.facebook.com/61550737114480/",
"root_reshared_post": null,
"byline": null,
"disclaimer_label": null,
"page_name": "Makhumalo",
"page_profile_picture_url": "https://scontent-sjc3-1.xx.fbcdn.net/v/t39.35426-6/499107970_2293645317822147_4932735414928456888_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DBNo3Z6ft4AQ7kNvwESjMWN&_nc_oc=AdnZGvglABgVlSJ6UIGIbWgFeUL2LnoBSuMbBvti20zRjb_UUDRzhGxAZ0ip3ye1EQI&_nc_zt=14&_nc_ht=scontent-sjc3-1.xx&_nc_gid=49D7P4N6a4mVqUW8WdOxag&oh=00_AfMEXcKVf3KYJpFehTTToe8MXUZslTHE9P-xS2eyVCeGKA&oe=685A4903",
"body": {
"text": "This is my second pair. I only take them off to go to sleep. I put them on first thing in the morning. I am 59 and have neuropathy in my feet, they bring me comfort every day.” -Lydia P.👍👍👍\n❤️These orthopedic shoes provide great comfort and ease foot and knee pain! 😍\n✅ Ideal for wide feet \n✅ comfortable \n✅ they are ideal for everyday life.\nGet Yours Now : https://www.ghemshop.com/products/buckled-square"
},
"is_reshared": false,
"brazil_tax_id": null,
"caption": "ghemshop.com",
"cards": [],
"cta_text": "Shop now",
"cta_type": "SHOP_NOW",
"country_iso_code": null,
"current_page_name": "Makhumalo",
"display_format": "IMAGE",
"event": null,
"images": [
{
"original_image_url": "https://scontent-sjc3-1.xx.fbcdn.net/v/t39.35426-6/499507599_4016645891948767_4341363175504946673_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=3EJ6TbZR3GEQ7kNvwErfuF4&_nc_oc=AdkQPpJ9OYN_J3P5xTetGSb9FDCFZzfoLSj59Bbp6s-g5HGg-zTECrgOm8mjkJfk5JE&_nc_zt=14&_nc_ht=scontent-sjc3-1.xx&_nc_gid=49D7P4N6a4mVqUW8WdOxag&oh=00_AfMTuIozb2-VJgGP7NCIx0pG91b48CzMgm_1eT7STgBvew&oe=685A6906",
"resized_image_url": "https://scontent-sjc3-1.xx.fbcdn.net/v/t39.35426-6/499504336_1222720305887055_488411876974522066_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=104&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DYkDYH-EJrQQ7kNvwF-b_ov&_nc_oc=Adn2l2fDwHaN4h6W-OxxgoYkb0IUAeCpYH5bociuO_oxVL9L0wLg5vqnNfJa0ehQwqY&_nc_zt=14&_nc_ht=scontent-sjc3-1.xx&_nc_gid=49D7P4N6a4mVqUW8WdOxag&oh=00_AfNkQcMpUNFcM7tF1M5tAHmVwABzLx5QKUU8CFo69NP3Rg&oe=685A4518",
"watermarked_resized_image_url": "",
"image_crops": []
}
],
"link_description": "🔥Best Seller-Last Day Sale 60% OFF🔥 Buckled Square Heel Sandals for Women",
"link_url": "https://www.ghemshop.com/products/buckled-square",
"page_categories": [
"Musician"
],
"page_entity_type": "PERSON_PROFILE",
"page_is_profile_page": false,
"page_like_count": 7,
"title": "🔥Best Seller-Last Day Sale 60% OFF🔥 Buckled Square Heel Sandals for Women",
"videos": [],
"additional_info": null,
"ec_certificates": [],
"extra_images": [],
"extra_links": [],
"extra_texts": [],
"extra_videos": []
},
"total_active_time": null,
"spend": null,
"start_date": 1747638000,
"publisher_platform": [
"FACEBOOK"
],
"url": "https://www.facebook.com/ads/library?id=1378176106734781",
"start_date_string": "2025-05-19T07:00:00.000Z",
"end_date_string": "2025-05-19T07:00:00.000Z"
}
],
"searchResultsCount": 50001,
"cursor": "AQHRLKHyzb3ZNTn1O3qr6lG7ncS9gfboI0HWGSDETVUnipTSXVY8E4Wb-568JBicOvYS",
"credits_charged": 1,
"credits_remaining": 1000,
"request_id": "00000000-0000-4000-8000-000000000000"
}Example data from the API specification. Run a request to retrieve current data.
Response shape
This schema describes the documented data shape. Some platform fields may be absent or null. The response also includes your FetchGoblin request ID and current credit balance.
View JSON Schema +
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"searchResults": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ad_archive_id": {
"type": "string"
},
"end_date": {
"type": "integer"
},
"is_aaa_eligible": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
},
"page_id": {
"type": "string"
},
"page_name": {
"type": "string"
},
"political_countries": {
"type": "array"
},
"reach_estimate": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"snapshot": {
"type": "object",
"properties": {
"branded_content": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"page_id": {
"type": "string"
},
"page_is_deleted": {
"type": "boolean"
},
"page_profile_uri": {
"type": "string"
},
"root_reshared_post": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"byline": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"disclaimer_label": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"page_name": {
"type": "string"
},
"page_profile_picture_url": {
"type": "string"
},
"body": {
"type": "object",
"properties": {
"text": {
"type": "string"
}
}
},
"is_reshared": {
"type": "boolean"
},
"brazil_tax_id": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"caption": {
"type": "string"
},
"cards": {
"type": "array"
},
"cta_text": {
"type": "string"
},
"cta_type": {
"type": "string"
},
"country_iso_code": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"current_page_name": {
"type": "string"
},
"display_format": {
"type": "string"
},
"event": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"original_image_url": {
"type": "string"
},
"resized_image_url": {
"type": "string"
},
"watermarked_resized_image_url": {
"type": "string"
},
"image_crops": {
"type": "array"
}
}
}
},
"link_description": {
"type": "string"
},
"link_url": {
"type": "string"
},
"page_categories": {
"type": "array",
"items": {
"type": "string"
}
},
"page_entity_type": {
"type": "string"
},
"page_is_profile_page": {
"type": "boolean"
},
"page_like_count": {
"type": "integer"
},
"title": {
"type": "string"
},
"videos": {
"type": "array"
},
"additional_info": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"ec_certificates": {
"type": "array"
},
"extra_images": {
"type": "array"
},
"extra_links": {
"type": "array"
},
"extra_texts": {
"type": "array"
},
"extra_videos": {
"type": "array"
}
}
},
"total_active_time": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"spend": {
"type": [
"string",
"object",
"array",
"number",
"boolean",
"null"
]
},
"start_date": {
"type": "integer"
},
"publisher_platform": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
},
"start_date_string": {
"type": "string"
},
"end_date_string": {
"type": "string"
}
}
}
},
"searchResultsCount": {
"type": "integer"
},
"cursor": {
"type": "string"
},
"credits_charged": {
"type": "integer",
"minimum": 0,
"description": "FetchGoblin credits charged for this request."
},
"credits_remaining": {
"type": "integer",
"description": "Your FetchGoblin credit balance after this request."
},
"request_id": {
"type": "string",
"format": "uuid",
"description": "FetchGoblin request identifier."
}
}
}