Facebook Ads Search

Search public Facebook Ads Library records by keyword, page ID, or direct Ads Library URLs. Returns ad archive IDs, page metadata, copy, CTA, media counts/assets, platforms, activity dates, and library URLs.

Execution Model

Live request

Runtime depends on endpoint, target, pagination, rendering mode, and active plan limits.

Credit Weight

Live catalog

Current weights are managed from the Data API Weights admin table and shown on pricing before use.

Parameters

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).

Response Fields

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.
source_url	string	Facebook Ads Library URL used.
time_taken	number	API response time in seconds.

cURL Example

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",
  "limit": 10,
  "scrapeAdDetails": true
}'

System Responses

200 OK

Request processed successfully.

401 UNAUTHORIZED

Missing or invalid API key.

429 RATE LIMIT

System capacity exceeded.

500 SYSTEM FAILURE

Internal core exception.

EXAMPLE RESPONSE

{
  "success": true,
  "source": "facebook_ads_library",
  "operation": "search",
  "runtime": "http_challenge_graphql",
  "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",
        "instagram"
      ],
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890"
    }
  ]
}