| hubs | No | advertisers: filter by hub/destination | |
| mode | No | scaling signal (dimension=scaling only): exploding, early_signal, revival, new or all. Omitted = all signals (the recommended base for custom threshold rules — run min_growth/min_new_ads/… across every signal); the SITE's default tab is exploding, so pass mode='exploding' to mirror it. | |
| limit | No | max rows to return (default 20; each delivered row costs 1 token). Ignored for geo_timeline: that dimension has no pagination and returns every populated date×country point in the accepted window while charging only the requested page size. | |
| format | No | creative format filter | |
| offset | No | scaling: pagination offset — skip the first N rows (use with limit to page through results). | |
| status | No | status filter: active or inactive. NOTE: 'vanished' is honored for ads/webmasters but NOT for dimension=advertisers (no advertiser-level vanished concept — use life_status for advertiser liveness). | |
| born_to | No | advertisers: page founded on or before this date (YYYY-MM-DD) | |
| country | No | single ISO country code filter (legacy form). Prefer countries[] for UI parity and multi-market requests; geo_timeline also accepts up to 200 comma-separated uppercase ISO-2 codes here, and omission means all geos | |
| date_to | No | end date YYYY-MM-DD; for geo_timeline supply together with date_from (both omitted = latest 30 days), max 31 inclusive days for all geos or 90 for a country subset | |
| signals | No | scaling tag classifier version: v2 = honest acceleration (base ≥3 ads over prior 3 days, growth vs 3-day average) and early_signal = fresh multi-account rollout ≤72h; default v1 (the current site behavior) | |
| sort_by | No | column to order the ranking by (dimension-specific, e.g. total_ads). NOTE on ranking: for dimension=advertisers, when a country/ai_category/hub filter is active the RELEVANT pages (smoothed concentration share >= 0.3 in the filtered vertical/geo) come first as a bucket, ordered INSIDE by the honest sort_by column desc — so the printed numbers descend within the relevant bucket and a metric top-N IS collectable; below the bucket sit low-share pages in the same column order. sort_by=active_ads orders by the geo-scoped active value the row displays; sort_by=coverage ranks purely by concentration. For dimension=scaling, sort_by accepts: growth (default), score (composite Spike-Score: a percentile blend of new-ad volume, base-honest growth multiplier, advertiser spread and freshness — each scaling row then also carries a spike_score 0-100), new_ads (most new ads yesterday — the today_ads metric), spread (widest advertiser spread — new fanpages), or freshness (newest creatives first by first_seen); sort_order is ignored (scaling always ranks DESC). | |
| baseline | No | scaling growth baseline: avg (default, window mean) or median (robust to a single outlier day). Affects the 3d/7d comparison window only; 1d is a no-op (single day). Default avg. | |
| platform | No | platform name filter (e.g. facebook, instagram) | |
| snapshot | No | scaling: snapshot source — v2 (default, 8-day detection window, the LIVE site behavior), v4 (37-day spike window, first_parsed_date axis; a PREVIEW contour) or long (Tier-2 Long Trend, 126-day WEEKLY window). ONLY snapshot=v4 unlocks spike_window, comparison=14d/30d, baseline=weekday, advertiser_ids, landing_changed, min_window_advertisers, min_active_now and the active_series/active_now/window_* fields; on v4 the active-history series is YOUNG (read days_of_active_history first). snapshot=long is a DIFFERENT tier — long-term Trend Growth (recent 30d new-ad rate vs the prior 90d baseline, per WEEK), NOT a spike: it accepts ONLY min_trend_growth / min_recent_new / min_advertisers / ai_category / ai_subcategory / media_types / sort=trend_growth|velocity, returns weekly_series[18] + trend_growth + recent_new_28d + prior_new_91d + prior_weekly_avg + window_advertisers with tag='trend_growth', and REFUSES (422) any spike-only param. On long the spike counters (today_ads, growth_multiplier, daily_history, currently_active, active_series, delta_*) are NOT populated — hydrate active/geo numbers per creative via get_creative (creative_id is the representative ad id). | |
| born_from | No | advertisers: page founded on or after this date (YYYY-MM-DD) | |
| countries | No | ISO country codes to INCLUDE. Mirrors the /trends geo include picker, which is multi-select: pass several markets in one call instead of one call per country. | |
| date_from | No | start date YYYY-MM-DD; for geo_timeline supply together with date_to (both omitted = latest 30 days), max 31 inclusive days for all geos or 90 for a country subset | |
| dimension | Yes | one of: geo, geo_timeline, advertisers, webmasters, apps, timeline, scaling, domains. geo_timeline is the batched per-country daily NEW-AD flow; use geo for current per-country stock. For creative trends use scaling (exploding/winning creatives). For BRANDS use domains — it ranks landing domains, the closest thing to a brand the data holds (advertisers are fanpages, webmasters are networks). | |
| same_text | No | scaling (snapshot=v4 ONLY): keep ONLY creatives whose title/hook is the SAME EXACT text — pass a title_norm_hash (a UInt64 as a decimal STRING, from a row's text cluster). This is same EXACT text, NOT 'same angle' (no embeddings). Template/boilerplate text (liquid {{…}}, bare URLs, confirmed CTA like 'Chat with us') is excluded. Ignored on snapshot=v2. | |
| verbosity | No | response size control: omit for the full payload, or compact to drop heavy per-row nested structures (geo: lifetime/geo_distribution; geo_timeline: is_complete, which meta already states for the whole window; timeline: lifetime; scaling: geo_distribution/active_series/daily_history/weekly_series). meta.omitted_row_fields lists exactly what was dropped. Use it when you only need the shape of a market and the full payload would not fit your context. | |
| comparison | No | scaling growth-comparison window: 1d, 3d or 7d. The numerator is always yesterday (d-1); the baseline is the average of that many prior COMPLETE days ending at d-2 — 1d = d-2, 3d = d-2..d-4, 7d = d-2..d-8 (a full seven days). Only these three presets exist on the default snapshot; 14d/30d require snapshot=v4. | |
| date_basis | No | timeline/geo date axis: fb_start (Facebook launch date — the honest axis for 'what the market launched', and the default here) or parsed (when Spytrend discovered the ad). ⚠️ The spytrend.com /trends page sends parsed by default, so to REPRODUCE a number a user sees on the site pass date_basis=parsed explicitly; the two axes differ because Spytrend also indexes older ads late. | |
| media_type | No | media type filter: image or video | |
| min_growth | No | scaling: minimum growth multiplier (today_ads ÷ prior-window average) — a FREE-FORM number, e.g. 2, 4.5 or 10 (not limited to x2/x5 presets). Omitted or 0 = NO growth threshold; the SITE's default is ×2, so pass min_growth=2 to mirror it. | |
| sort_order | No | sort direction: asc or desc | |
| store_type | No | apps ONLY: store type (e.g. android, ios). Has NO effect on dimension=advertisers. | |
| ai_category | No | AI category slug filter (e.g. gambling_and_betting) | |
| life_status | No | advertisers only: page life status — alive, deleted or banned | |
| max_new_ads | No | scaling: at most N new ads yesterday — combine with min_new_ads for a band, e.g. 10..50. 0 / omitted = no upper bound. | |
| min_new_ads | No | scaling: minimum NEW ads yesterday — the today_ads metric on each scaling row — free-form integer (e.g. 8). 0 / omitted = no threshold. | |
| creative_age | No | scaling: creative age bucket by first_seen — new (≤3 days), fresh (3-14 days), proven (14-60 days) or old (60+ days). A preset alternative to max_first_seen_hours; combine with it and both narrow. Omitted = no age filter. | |
| spike_window | No | scaling (snapshot=v4 ONLY): spike window in days — 1, 2, 3 or 7. The growth numerator becomes the per-day average of NEW launches over the last W complete days (1 = yesterday, the v2 form). Does NOT change the tag chips (they stay on the fixed yesterday-vs-3-day window). Ignored on snapshot=v2. | |
| webmaster_id | No | restrict the ranking to ads of this webmaster/affiliate id (from search_webmasters). Mirrors the visible /trends webmaster dropdown. Not honored on rollup-backed dimensions — the response then reports it in meta.unsupported_filter instead of silently ignoring it. | |
| first_seen_to | No | only ads spytrend first INDEXED on or before this date (YYYY-MM-DD) — internal discovery date, not the Facebook launch date; for 'new ads' questions use date_from/date_to. See first_seen_from for exact-total windows | |
| followers_max | No | advertisers: maximum page followers | |
| followers_min | No | advertisers: minimum page followers | |
| min_geo_share | No | advertisers only: dominant-geo gate (0-1) — keep only advertisers whose share of ads in the selected country is at least this fraction (e.g. 0.5 = the country is >=50% of the page's ads). Requires country. Without it the country filter is a mere present-in match: a page with 25% of its ads in GB still ranks in the GB top . Share is computed from the page's total per-country ad distribution; a per-country ACTIVE slice is not tracked. | |
| advertiser_ids | No | scaling (snapshot=v4 ONLY): competitor filter — comma-separated advertiser UUIDs; keep only creatives run by ANY of them (hasAny). Invalid UUIDs are dropped; capped at 100. Ignored on snapshot=v2. | |
| ai_subcategory | No | AI subcategory slug filter | |
| min_active_now | No | scaling (snapshot=v4 ONLY): keep creatives with ≥ N ads active RIGHT NOW (active_now). 0 / omitted = no threshold (no default preset). Ignored on snapshot=v2. | |
| min_recent_new | No | scaling (snapshot=long ONLY): minimum recent_new_28d — new ads first seen in the last 28 days (the velocity numerator). 0 / omitted = no threshold. Ignored unless snapshot=long. | |
| first_seen_from | No | only ads spytrend first INDEXED on or after this date (YYYY-MM-DD) — an internal discovery date, NOT the ad's Facebook launch date. Do NOT use it for 'new ads recently' questions: spytrend also indexes OLD ads late, so late-indexed old ads would pollute the answer — use date_from/date_to (Facebook launch) for market newness. Exact totals: any closed window up to 31 days; a single-country request with only AI-category filters can use the canonical daily cube for up to 90 days or from this date through today | |
| landing_changed | No | scaling (snapshot=v4 ONLY): landing-page-change filter — any (default), same (one landing domain over the window), new (a new landing appeared) or multiple (2+ landings — affiliate/cloaking distribution). Ignored on snapshot=v2. | |
| min_advertisers | No | scaling (snapshot=long ONLY): minimum advertisers_total — unique advertisers that ran the creative over the 126-day window (market spread). 0 / omitted = no threshold. Ignored unless snapshot=long. | |
| min_days_active | No | only rows whose entity has ads running at least this many days | |
| min_new_domains | No | scaling: minimum NEW webmasters/domains (new_webmasters) running the creative — the domain-spread signal, mirror of min_new_accounts — free-form integer (e.g. 3). 0 / omitted = no threshold. | |
| min_text_spread | No | scaling (snapshot=v4 ONLY): keep creatives whose EXACT text is shared by ≥ N families (the text-spread market signal — 'this script is being copied by N families', doc §16.5). Only non-template text counts. Each returned row also carries text_spread (families sharing its text) when ≥2 and non-boilerplate. 0 / omitted = no threshold. Ignored on snapshot=v2. | |
| min_new_accounts | No | scaling: minimum NEW accounts (new advertiser fanpages) running the creative — free-form integer (e.g. 6). 0 / omitted = no threshold. | |
| min_trend_growth | No | scaling (snapshot=long ONLY): minimum trend_growth — (new ads over the last 30d ÷ 4 weeks) ÷ (new ads over the prior 90d ÷ 13 weeks), i.e. the recent per-week new-ad rate vs the baseline per-week rate. Free-form float (e.g. 1.5, 2, 3); >1 = sustained growth. 0 / omitted = no threshold. Ignored unless snapshot=long. | |
| exclude_countries | No | ISO country codes to EXCLUDE — drops rows whose ads target ANY of them. Mirrors the /trends geo EXCLUDE column. Honored on timeline (and the webmaster-scoped path); NOT applicable to geo_timeline, whose rows are per-country cube aggregates rather than per-ad geo arrays — that response names it under meta.ignored_filters instead of pretending it ran. | |
| min_category_share | No | advertisers only: vertical-share gate (0-1) — keep only advertisers whose share of ads in the selected ai_category/ai_subcategory is at least this fraction (e.g. 0.2). Requires ai_category or ai_subcategory. Without it the category filter is a presence match: a travel agency with 4% of its ads in gambling still ranks in the gambling top. Share is the same number as the category percentage shown on the advertiser card. | |
| max_first_seen_hours | No | scaling: keep only creatives first seen within the last N hours — your own freshness window (the 'new' preset is fixed at 48h; this is free-form, e.g. 24 or 72). | |
| min_window_advertisers | No | scaling (snapshot=v4 ONLY): market-trend threshold — keep creatives with ≥ N unique advertisers over the 37-day window (the 'spreading across the market' signal, doc §16.5). 0 / omitted = no threshold. Ignored on snapshot=v2. | |
