Facebook Ads Search

Facebook Ads Search Endpoint

Search the public Ads Library from a keyword, page, or library URL.

Getting Started

Send your API key as a bearer token. Start with the smallest request below.

Search Ads

Send one source: query, page_id, url, or urls.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "country": "IN",
  "limit": 10
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Search Sources

Search a Page

Set page_id to return ads associated with one Facebook page.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "page_id": "123456789",
  "country": "IN",
  "limit": 10
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Use a Library URL

Send url for one Ads Library source.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://www.facebook.com/ads/library/?id=1234567890",
  "country": "IN"
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Use Multiple Library URLs

Send urls for a bounded batch of Ads Library sources.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "urls": [
    "https://www.facebook.com/ads/library/?id=1234567890",
    "https://www.facebook.com/ads/library/?id=1234567891"
  ],
  "country": "IN"
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Ad Filters

Filter Status and Media

Set country, active_status, and media_type to narrow results.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "country": "IN",
  "active_status": "active",
  "media_type": "video"
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Filter Dates and Platforms

Set start_date, end_date, and publisher_platforms for a bounded campaign view.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "country": "IN",
  "start_date": "2026-01-01",
  "end_date": "2026-06-30",
  "publisher_platforms": [
    "facebook",
    "instagram"
  ]
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Details and Pagination

Include Ad Details

Set scrape_ad_details to include available snapshot media and detail fields.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "country": "IN",
  "scrape_ad_details": true,
  "limit": 10
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Continue with a Cursor

Send the previous cursor and set limit from 1 to 50.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "country": "IN",
  "cursor": "NEXT_CURSOR",
  "limit": 25
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Request Controls

Set Provider Timeout

Set timeout_ms from 5,000 to 90,000 milliseconds.

curl -X POST "https://api.datablue.dev/v1/data/facebook-ads/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "timeout_ms": 45000
}'

Example response

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "query": "kiro beauty",
  "country": "IN",
  "total_results": 1,
  "time_taken": 2.5,
  "ads": [
    {
      "position": 1,
      "ad_archive_id": "1234567890",
      "is_active": true,
      "page_name": "Kiro Beauty",
      "body": "Clean beauty essentials",
      "cta_text": "Shop Now",
      "image_count": 1,
      "video_count": 0,
      "publisher_platforms": [
        "facebook"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}

Response

Consume normalized rows from ads; use has_next_page and cursor for pagination.

Error Handling

Handle 401 for authentication, 422 for invalid input, 429 for limits, and retry only transient failures.

Name	Type	Requirement	Description
query	string	Optional	Keyword search query. Required unless url, urls, or page_id is supplied.
url	string	Optional	Direct Facebook Ads Library URL.
urls	string[]	Optional	Batch of direct Ads Library URLs.
country	string	Optional	Two-letter country code.
active_status	string	Optional	all, active, or inactive.
media_type	string	Optional	Media type filter.
page_id	string	Optional	Facebook page ID.
start_date	string	Optional	Start date filter.
end_date	string	Optional	End date filter.
publisher_platforms	string[]	Optional	Publisher platforms such as facebook or instagram.
scrape_ad_details / scrapeAdDetails	boolean	Optional	Return full snapshot media/detail fields when available.
limit / count / limitPerSource	number	Optional	Maximum ads to return (1-50).
cursor	string	Optional	Pagination cursor from a previous response.
timeout_ms	number	Optional	Provider timeout in milliseconds (5000-90000).

Field	Type	Description
success	boolean	Whether the request completed successfully.
ads	array	Ad rows with ad_archive_id, active status, page metadata, body, title, caption, CTA, link URL, images, videos, platforms, dates, reach/spend, and ad_library_url.
cursor / has_next_page	string \| boolean	Pagination metadata.
time_taken	number	API response time in seconds.