Search creatives
search_creativesBrowse and filter Meta creative families (source=meta only; TikTok callers must use search_ads with source=tiktok and dedupe=true) and return metadata only. Filters include country/countries, exclude_countries, categories, ai_subcategory, media_type/media_types, domain_zone, advertiser_id/advertiser_ids, webmaster_id, fanpages, hub_domains/channel, active_ads_today_from, last_seen_from/to, period_from/to, max_countries, min_geo_share, folder_id and saved=all. last_seen_from/to is creative activity eligibility; period_from/to (date_from/to aliases) is the independent in-period window for ads_in_period — the window itself does NOT filter rows (total and rows stay the same); add ads_in_period_from=N to keep only creatives with at least N ads in it (not yet with country/countries). The applied window is echoed in meta.period_window. Sort by relevance, total_ads, ads_in_period/reuploads, active_ads, last_seen or fb_created. With an advertiser/webmaster slice, pagination.sort_semantics=slice_ordered_by_webmaster|slice_ordered_by_advertiser and slice.ads_in_slice is the ordering key. total_ads remains the lifetime whole-family count; ads_in_period is the count for the selected period on the backend-reported date axis. Always read pagination.period_axis: first_seen means first discovery by Spytrend; facebook_start_date means launch on Facebook after the verified launch-generation cutover. query/search_in searches the texts of the creative family's ads; all query words must match the family. Cursor-paginated. Download with get_media and save with add_to_favorites. DATA COVERAGE: pagination.total_status is exact, estimated or unavailable, and for free plans restricted; when the requested dates (or the newest-first order, or an open-ended date range) reach past the day every creative is complete through (meta.data_through) it is partial (some creatives have those days, the rest do not yet) or stale (no creative reaches the requested days). meta.served_through is the newest day any creative reaches (absent when it could not be read; the verdict is then never stale) and meta.coverage_note repeats both. A stale or partial zero or short page means there is no data for those days yet, never that no creatives exist, so say the data is complete through meta.data_through and partly available up to meta.served_through. QUOTA: 1 MCP credit per DELIVERED result (default page 20 = 20 MCP credits; short pages auto-refund). Results carry metadata only; get_ad/get_media charge 50 MCP credits per multilang-upload ad opening, 1 per ordinary ad, and get_media charges 10 per creative-catalogue item. Each new opening call is billed separately. Meta search_ads rows include is_multilang and opening_price (Spytrend MCP credits per ad per call); unavailable/null means the price could not be verified, not zero. is_multilang=true marks a multi-language upload («залив языками»): a masked carousel where some slides are decoys for ad review; where the real (black) slide is found it is the one shown first and used for grouping. multilang_black_missing=true means the real slide is not found yet: the media shown is a decoy and must not be treated as the creative. Opening quotes are not a debit or a price lock. Request small limits and narrow filters. PERIOD PARITY CONTRACT: the /creo web filters ai_subcategory, hub_domains[] and active_ads_today_from are available here too. last_seen_from/to filters the creative's LAST recorded activity and does not change count semantics. period_from/period_to is the independent inclusive window used for ads_in_period; date_from/date_to are compatibility aliases of it and, unlike search_ads.date_from, do not filter rows — ads_in_period_from does. A closed explicit period enables ads_in_period automatically. sort_by=ads_in_period or reuploads ranks by that measured in-period count, while total_ads remains lifetime family reuse. The legacy period_metric=ad_debuts plus closed last_seen bounds remains accepted temporarily. Empty pages do not fabricate a count. Invalid/open/reversed periods are rejected before quota or upstream work, and a backend response missing ads_in_period is rejected rather than presented as zero. AXIS CONTRACT: read pagination.period_axis on every period response. "first_seen" means the ad was first discovered by Spytrend; "facebook_start_date" means the ad was launched on Facebook, and is emitted only after the verified launch-generation cutover. Never assume an axis from the request or description. PRICING: price × number of filters set (min 1), on paid plans ×1 after 500 MCP credits/month; one-time consent via accept_pricing_terms; before calling, get the maximum debit from estimate_cost (free) and tell the user.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search_creatives"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | max metadata rows (default 20, max 200; each delivered row costs 1 MCP credit) — fetch media with get_media (entity_type=creo, 10 MCP credits per creative). | |
| query | No | free-text keyword search over the creative FAMILY: every word must appear in the texts of the creative's ads (all of them, not one representative ad). Combine with any other filter; use search_in to narrow the area. | |
| saved | No | saved scope selector. Use saved=all to restrict results to creatives saved in ANY favourites folder. | |
| cursor | No | pagination cursor | |
| source | No | creative catalogue source: meta (default). TikTok is not supported by this tool; use search_ads with source=tiktok and dedupe=true for TikTok ad representatives. Unsupported sources are rejected before charging. | |
| channel | No | messaging channel the creative sends traffic to: whatsapp or telegram. Filters to creatives landing on that channel's chat domains. Use for 'bundles going to WhatsApp/Telegram'. | |
| country | No | ISO-2 country code to filter creatives shown in that geo (e.g. US, BR). Country may be combined with categories, ai_subcategory, media_type/media_types, max_countries, advertiser_id/advertiser_ids, webmaster_id, fanpages, hub_domains, domain_zone, active_ads_today_from, last_seen dates, min_geo_share and supported sorting filters. Do not combine a country scope with hub_category or channel. | |
| date_to | No | ALIAS of period_to (YYYY-MM-DD). It sets the window of the ads_in_period metric and does NOT filter rows — unlike search_ads.date_to. To keep only creatives with ads in the window add ads_in_period_from=1. The applied window is echoed in meta.period_window; read pagination.period_axis for its date axis. | |
| sort_by | No | order by: relevance (needs country), total_ads (lifetime), ads_in_period/reuploads (count in a closed period; read pagination.period_axis for its date axis), active_ads, last_seen or fb_created | |
| fanpages | No | the /creo fanpages filter: keep only creatives that ran on ANY of these fanpage ids (advertiser external_ids — the Facebook page ids; OR-semantic). Entries may also be pasted facebook.com page links in any form (vanity, profile id, Ads Library) — each is resolved to its canonical page id. Get page ids from get_creative's fanpages, an ad's page_id (search_ads), or get_advertiser's external_id. Max 50. | |
| countries | No | ISO country codes to INCLUDE. The visible /creo geo picker is a multi-select — pass several markets in one call instead of one call per country. | |
| date_from | No | ALIAS of period_from (YYYY-MM-DD). It sets the window of the ads_in_period metric and does NOT filter rows — unlike search_ads.date_from, the result set and total stay the same. To keep only creatives with ads in the window add ads_in_period_from=1. The applied window is echoed in meta.period_window; read pagination.period_axis for its date axis. | |
| folder_id | No | restrict results to creatives saved in this favourites folder UUID. Mirrors the /creo folder view. | |
| period_to | No | in-period window end (YYYY-MM-DD), independent from creative last activity; requires period_from; read pagination.period_axis to learn which date axis was used | |
| search_in | No | where to search when query is set: all (default - ad headline/link text/CTA, fan page names, landing domains AND ad body text), title (headline/link description/CTA), text (ad body text), advertiser (fan page names). Ignored without query. | |
| categories | No | AI category slugs to filter by (e.g. gambling_and_betting, impersonation_funnels, crypto_and_trading). Multiple = OR. | |
| media_type | No | media type filter: image or video | |
| sort_order | No | sort direction: asc or desc | |
| domain_zone | No | landing-domain zones/TLDs without the dot (e.g. com, shop, online). Mirrors the /creo domain-zone filter. | |
| hub_domains | No | exact destination hostnames to include (the web Hub filter). Use domains as a compatibility alias if needed; values are normalized hostnames, maximum 50. | |
| media_types | No | media types to include (image, video) — the visible /creo media multi-select. Prefer this over the singular media_type. | |
| period_from | No | in-period window start (YYYY-MM-DD), independent from creative last activity; requires period_to; read pagination.period_axis to learn which date axis was used | |
| hub_category | No | filter to creatives whose destination is in this TOP-LEVEL hub category. Valid slugs: social, app_stores, shortlinks, amazon, ecommerce, popular, platforms (NOT 'social_media' — the slug is 'social'). For a specific messaging channel use channel - hub_category does NOT accept whatsapp/telegram sub-slugs. | |
| last_seen_to | No | date range end (YYYY-MM-DD): only creatives whose LAST recorded activity is on or before this date. Combine with last_seen_from for a closed activity window. | |
| webmaster_id | No | only creatives used by this webmaster id (from search_webmasters) | |
| advertiser_id | No | only creatives run by this INTERNAL advertiser UUID (search_advertisers field advertiser_id, an ad's advertiser_id in search_ads, or get_trends dimension=advertisers). A Facebook page id or page link sent here is applied as the fanpages filter when fanpages is empty (reported in params.normalized); any other value is rejected. | |
| max_countries | No | only creatives shown in at most this many countries | |
| min_geo_share | No | D1 geo-relevance FILTER (0-1): keep only creatives where 'country' is at least this share of the creative's ads — i.e. that geo is the creative's dominant / #1 country (e.g. 0.5 = the country is >=50% of its ads). Requires country. Combine with sort_by=relevance to rank by ad-volume IN that country. | |
| period_metric | No | derived in-period metric: ad_debuts counts ads in the inclusive period_from/period_to window on the backend-reported date axis; pagination.period_axis explains the result (first_seen = first discovery by Spytrend, facebook_start_date = Facebook launch after the verified cutover) | |
| advertiser_ids | No | multi-select advertiser filter: creatives run by ANY of these advertiser UUIDs (OR). Each returned card then carries slice.ads_in_slice / slice.active_in_slice = the EXACT summed ad counts of exactly these advertisers inside the creative's family (additive — an ad belongs to one advertiser). Supersedes advertiser_id when both are sent. | |
| ai_subcategory | No | AI subcategory slugs to filter by. Multiple = OR; combine with categories when needed. | |
| last_seen_from | No | date range start (YYYY-MM-DD): only creatives whose LAST recorded activity/fixation is on or after this date. This activity filter is independent from period_from/period_to; it is not an interval-overlap or first-seen filter. | |
| exclude_countries | No | ISO country codes to EXCLUDE: a creative targeting ANY of them is hidden. Mirrors the /creo geo EXCLUDE column. | |
| ads_in_period_from | No | row FILTER on the period window: keep only creatives with at least this many ads counted in ads_in_period for the closed period_from/period_to (or date_from/date_to) window, e.g. 1 = creatives with at least one ad in the window. Requires the closed window. Not available together with country/countries yet (the per-country period series is not maintained, so it would return a false empty page); such calls are refused, not answered with 0. | |
| active_ads_today_from | No | minimum number of ads active today for the creative family; 0 or omitted disables this filter |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| meta | No | ||
| error | No | Present only when isError is true: machine-readable failure. The human explanation stays in content. | |
| params | No | Request parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason. | |
| pagination | No | ||
| addon_hints | No | Add-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about. |