Search the Ad Library
search_adsRead-onlyIdempotent
Searches the StealAds Ad Library of public Meta ads by advertiser name, website or keywords, with filters for format, run length, industry, buyer, hook and angle. Returns up to 24 ads per page (default 12) with caption, hook, run dates, delivery evidence and image URLs, plus next_cursor. For a named advertiser or a specific topic; find_winning_ads suits open category inspiration. Results are a capped sample without library totals or complete advertiser coverage. Keyword matching is broad, so rows can be off-topic. Run time is delivery evidence, not proof of sales.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "search_ads"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| angle | No | Exact angle filter from a row’s filters.angle, e.g. social_proof. Absent means no filter. | |
| buyer | No | Who pays: business_owners = owners/operators; consumers = end consumers; professionals = business buyers or practitioners; any = no buyer filter. With a buyer filter, exact matches come back in ads and unknown-profile or adjacent business buyers in a separate nearby group (at most 25% of the page); exact_count and nearby_count report each group. | |
| query | Yes | Advertiser name, website or product keywords, e.g. protein powder. Up to 200 characters. | |
| cursor | No | next_cursor from the previous page with the same query and filters; absent for the first page. A page can be empty while has_more is true. | |
| format | No | static = image ads; video = video ads. Absent means both. | |
| audience | No | Who it targets, e.g. restaurant owners or main street business owners. Ranks stored audience, buyer label, industry and ad-copy evidence. When supplied, industry_slug is a hard constraint; inferred categories can broaden. | |
| brand_id | No | Optional brand id from list_brands. Marks rows from that brand's competitors with your_rival; narrows nothing unless tracked_rivals_only is true. | |
| hook_type | No | Exact hook filter from a row’s hook_type_filter, e.g. urgency. Absent means no filter. | |
| max_results | No | Ads per page, 1 to 24 (default 12). | |
| min_run_days | No | Only ads observed running for at least this many days (0 to 36500). | |
| presentation | No | Display hint; search returns data only. Selected results can be displayed by show_ad_gallery. | |
| competitor_id | No | Restricts results to one saved competitor: a competitor id from list_competitors. | |
| industry_slug | No | Industry slug from a row’s filters.industry_slug, e.g. fitness-software. Parent categories include their child categories; a leaf category selects that exact category. Absence permits inferred related categories. | |
| search_angles | No | Up to three related products, offers or advertiser names that widen a category_leaders search; refused with exact intent. Not format or hook labels. | |
| search_intent | No | exact (default) matches the query words or advertiser and supports cursors. category_leaders samples the category across related angles in one page without a cursor, as find_winning_ads does. | |
| has_spoken_hook | No | true: only ads with an extracted spoken (verbal) hook. false: only ads without one. Absent means all ads. | |
| response_format | No | Output format: text (default) is readable text with image previews and links; json returns the structured rows. table is refused by Ad Library tools. | |
| facebook_page_id | No | Restricts results to one advertiser: a facebook_page_id from search_advertisers. | |
| tracked_rivals_only | No | true restricts results to ads from the brand's tracked competitors; needs brand_id. |