search_ads
Search and rank verified Meta or Google ad creatives across tracked shops or a bounded global concept.
Use search_ads when the user asks for concrete ad creatives, hooks, formats, active ads, recent launches, reach or longevity.
Inputs
| Field | Type | Notes |
|---|---|---|
storeIds | string[] | Zero to five tracked shops |
concept | string | Optional global concept, 2–120 characters |
query.limit | number | 1–12, defaults to 6 |
query.source | enum | all, meta, google |
query.countries | string[] | Up to 10 uppercase country codes |
query.formats | enum[] | video, image, carousel, dco |
query.placements | enum[] | Facebook, Instagram, Messenger, Audience Network, Threads |
query.status | enum | all, active, inactive |
query.sort | enum | reach, recent, longest |
query.dateWindowDays | number | 1–365 |
query.dateMode | enum | launched or observed |
query.languages | string[] | Up to five lowercase language codes |
query.cta | string | Optional CTA filter |
Example
{
"storeIds": ["store_gymshark"],
"query": {
"limit": 6,
"source": "meta",
"countries": ["US"],
"formats": ["video"],
"placements": ["instagram"],
"status": "active",
"sort": "longest",
"dateWindowDays": 90
}
}Choosing a date mode
Use launched when the user cares when an ad began. Use observed when they care when WhatWins verified the record. Meta can reset displayed start dates when an ad is edited or relaunched; WhatWins evidence should therefore preserve and explain the distinction between launch dates and observation history.
Credit behavior
The maximum reservation is query.limit × max(1, number of stores). The final charge reflects ads actually returned.