meta-ad-library_meta-ads_library_search $0.001 per call

Search the Meta ad library by keyword. Search publicly running Facebook and Instagram ads by keyword (Meta Ad Library · Meta Ads (Facebook & Instagram))

For AI agents: call meta-ad-library_meta-ads_library_search
POST https://toll402.dev/v1/p/meta-ad-library.meta-ads.library.search
{
 "search_terms": "project management software",
 "search_type": "KEYWORD_UNORDERED",
 "ad_reached_countries": [
  "US"
 ],
 "fields": "id,page_id,page_name,ad_creative_bodies,ad_creative_link_titles,ad_creative_link_captions,ad_snapshot_url,ad_delivery_start_time,ad_delivery_stop_time,publisher_platforms,languages,estimated_audience_size",
 "ad_active_status": "ALL",
 "ad_type": "ALL",
 "ad_delivery_date_min": "2026-06-01",
 "media_type": "VIDEO",
 "publisher_platforms": [
  "INSTAGRAM"
 ],
 "languages": [
  "en"
 ],
 "limit": 25
}
Answers 402 with x402 payment requirements; pay with any x402 client (@x402/fetch, x402 for Python, toll402-client, toll402-mcp) or send a prepaid-credits key as x-toll402-key (https://toll402.dev/credits). Paid per call via x402 (USDC on Base) or with a prepaid-credits key (x-toll402-key, card at /credits); charged only on success. Start at /llms.txt or connect the MCP server: npx -y toll402-mcp · remote https://toll402.dev/mcp.

Input schema

{
 "type": "object",
 "properties": {
  "search_terms": {
   "type": "string",
   "description": "max 100 characters; matched against the ad's text. Required in practice unless you filter by search_page_ids instead",
   "examples": [
    "project management software"
   ]
  },
  "search_type": {
   "type": "string",
   "description": "KEYWORD_UNORDERED (default, all words in any order) | KEYWORD_EXACT_PHRASE",
   "examples": [
    "KEYWORD_UNORDERED"
   ]
  },
  "ad_reached_countries": {
   "type": "array",
   "description": "REQUIRED on every ads_archive call. JSON array of ISO country codes, URL-encoded — [\"US\"] — or ALL",
   "examples": [
    [
     "US"
    ]
   ]
  },
  "fields": {
   "type": "string",
   "description": "comma-separated; nothing but id comes back by default",
   "examples": [
    "id,page_id,page_name,ad_creative_bodies,ad_creative_link_titles,ad_creative_link_captions,ad_snapshot_url,ad_delivery_start_time,ad_delivery_stop_time,publisher_platforms,languages,estimated_audience_size"
   ]
  },
  "ad_active_status": {
   "type": "string",
   "description": "ACTIVE (default) | INACTIVE | ALL — ALL is what you want for creative research, since a competitor's best-performing ad may have finished",
   "examples": [
    "ALL"
   ]
  },
  "ad_type": {
   "type": "string",
   "description": "ALL (default) | POLITICAL_AND_ISSUE_ADS | HOUSING_ADS | EMPLOYMENT_ADS | FINANCIAL_PRODUCTS_AND_SERVICES_ADS",
   "examples": [
    "ALL"
   ]
  },
  "ad_delivery_date_min": {
   "type": "string",
   "description": "YYYY-MM-DD; ads that were delivering on or after this date",
   "examples": [
    "2026-06-01"
   ]
  },
  "ad_delivery_date_max": {
   "type": "string",
   "description": "YYYY-MM-DD"
  },
  "media_type": {
   "type": "string",
   "description": "ALL | IMAGE | MEME | VIDEO | NONE",
   "examples": [
    "VIDEO"
   ]
  },
  "publisher_platforms": {
   "type": "array",
   "description": "FACEBOOK | INSTAGRAM | AUDIENCE_NETWORK | MESSENGER | WHATSAPP | OCULUS | THREADS",
   "examples": [
    [
     "INSTAGRAM"
    ]
   ]
  },
  "languages": {
   "type": "array",
   "description": "ISO 639-1 codes (plus CMN, YUE)",
   "examples": [
    [
     "en"
    ]
   ]
  },
  "estimated_audience_size_min": {
   "type": "integer",
   "description": "one of the fixed buckets 100 | 1000 | 5000 | 10000 | 50000 | 100000 | 500000 | 1000000"
  },
  "limit": {
   "type": "integer",
   "description": "page size; 25 by default, a few hundred is the practical ceiling before Meta starts timing out",
   "examples": [
    25
   ]
  },
  "after": {
   "type": "string",
   "description": "paging.cursors.after from the previous response"
  }
 },
 "additionalProperties": true,
 "required": [
  "ad_reached_countries",
  "fields"
 ],
 "description": "give it either search_terms or search_page_ids — a call with neither returns an error, not the whole library. ad_snapshot_url is the human-viewable render of the creative and needs the access token appended to load. Results are ads Meta has KEPT: commercial ads leave the library some time after they stop running, so this is a live-ish view, not an archive"
}

MCP

{"mcpServers":{"toll402":{"command":"npx","args":["-y","toll402-mcp"],"env":{"TOLL402_WALLET_KEY":"0x..."}}}}

All tools · OpenAPI