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