Search

GET /v1/facebook/adLibrary/search/ads

Searches the Meta Ad Library by keyword and returns matching ads. Each result includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body text, images, videos, and cta_text. Results cap around 1,500 via GET due to cursor size limits; switch to POST method with body params for larger result sets.

Authentication

All requests require the x-api-key header. Get your key at scrapecreators.com.

Query Parameters

Name	Type	Required	Description	Example
`query`	string	yes	Keyword to search for	`running`
`sort_by`	enum(total_impressions, relevancy_monthly_grouped)	no	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.	`total_impressions`
`search_type`	enum(keyword_unordered, keyword_exact_phrase)	no	If you want to search by exact phrase or not	`keyword_unordered`
`ad_type`	enum(all, political_and_issue_ads)	no	Search for all ads or only political and issue ads	`all`
`country`	string	no	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.	`ALL`
`status`	enum(ALL, ACTIVE, INACTIVE)	no	Status of the ad. Defaults to ACTIVE.	`ACTIVE`
`media_type`	enum(ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE)	no	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.	`ALL`
`start_date`	string	no	Impressions start date. Needs to be in YYYY-MM-DD format.	`2025-01-05`
`end_date`	string	no	Impressions end date. Needs to be in YYYY-MM-DD format.	`2025-02-16`
`cursor`	string	no	Cursor to paginate through results	`AQHRYLVDkoMkvGv7yK1rcce-vJmKiKv330R4v3j9KHSOaYvmF1bq1QkotG0rgW8Fkrj-`
`trim`	boolean	no	Set to true for a trimmed down version of the response	`false`

Example Request

curl

bash

curl 'https://api.scrapecreators.com/v1/facebook/adLibrary/search/ads?query=running' \
  -H 'x-api-key: $SCRAPECREATORS_API_KEY'

Node / TypeScript

const params = new URLSearchParams({ query: 'running' });
const res = await fetch(`https://api.scrapecreators.com/v1/facebook/adLibrary/search/ads?${params}`, {
  headers: { 'x-api-key': process.env.SCRAPECREATORS_API_KEY }
});
const data = await res.json();
console.log(data);

Python

python

import os, requests
r = requests.get(
    'https://api.scrapecreators.com/v1/facebook/adLibrary/search/ads',
    headers={'x-api-key': os.environ['SCRAPECREATORS_API_KEY']},
    params={'query': 'running'},
)
r.raise_for_status()
print(r.json())

CLI

bash

scrapecreators facebook-ads adLibrary-search-ads --help

Example Response

json

{
  "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",
     
... (truncated)

Credits

Most ScrapeCreators endpoints consume 1 credit per successful response. Some heavier endpoints (transcripts, AI-driven enrichment, ad detail lookups) may cost more. Check GET /v1/credit-balance for your remaining balance.

Errors

Status	Meaning	Action
200	Success.	Use the JSON payload.
400	Invalid or missing parameter.	Verify required parameters and value format.
401	Missing or invalid `x-api-key`.	Pass a valid API key in the header.
402	Out of credits.	Top up at scrapecreators.com or wait for plan reset.
404	Resource not found or private.	Confirm the handle, URL, or id and that the resource is public.
429	Rate limited.	Backoff and retry with exponential delay.
500	Server error or upstream platform failure.	Retry with backoff; report persistent errors to support.

Search ​

Authentication ​

Query Parameters ​

Example Request ​

curl ​

Node / TypeScript ​

Python ​

CLI ​

Example Response ​

Credits ​

Errors ​