Spytrend

Search creatives

search_creatives

Read-only

Browse 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. 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. QUOTA: 1 token per DELIVERED result (default page 20 = 20 tokens; short pages auto-refund). Results carry metadata only; get_ad/get_media charge 50 tokens 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 tokens per ad per call); unavailable/null means the price could not be verified, not zero. 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. 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.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	max metadata rows (default 20, max 200; each delivered row costs 1 token) — fetch media with get_media (entity_type=creo, 10 tokens 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	compatibility alias of period_to for the in-period window; read pagination.period_axis to learn which date axis was used
`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	compatibility alias of period_from for the in-period window; read pagination.period_axis to learn which date axis was used
`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 advertiser id (from an ad's advertiser_id in search_ads, or get_trends dimension=advertisers)
`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.
`active_ads_today_from`	No	minimum number of ads active today for the creative family; 0 or omitted disables this filter

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	Yes
`meta`	No
`pagination`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 14, 2026

changedInput schema / properties / last_seen_from / description

Previous value: -"date range start (YYYY-MM-DD): only creatives whose LAST recorded activity/fixation is on or after this date. This is the ONLY date filter; it is not an interval-overlap or first-seen filter."New value: +"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."

addedInput schema / properties / source

Added value: +{
+  "description": "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.",
+  "enum": [
+    "meta",
+    "tiktok"
+  ],
+  "type": "string"
+}

First observedSep 2, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description goes substantially further: full quota model (1 token per delivered result, short pages refunded, 50 tokens per multilang ad opening, 10 per catalogue item, billed separately), period parity contract, axis contract, rejection-before-charge guarantees, and empty-page semantics. This is rich beyond what annotations provide, though the density borders on documentation-level rather than concise disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and largely front-loaded with the meta-only scoping and sibling routing first, which is good. However, it is extremely long for a tool description, with duplicated contract material (PERIOD PARITY CONTRACT and AXIS CONTRACT restate much of what is already in the schema descriptions for period_from/period_to, sort_by, and last_seen fields). Several sentences repeat concepts already covered by the schema, reducing signal density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 34 parameters, 100% schema coverage, an output schema, and rich annotations, the description is more than complete—it covers quota semantics, period parity, axis semantics, and rejection behavior that the structured fields alone would not convey. It arguably over-delivers on completeness at the expense of conciseness, but nothing an agent needs to invoke correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all 34 parameters in depth, establishing a baseline of 3. The description adds meaning beyond the schema by grouping filters, clarifying cross-parameter interactions (country cannot combine with hub_category or channel; advertiser_ids supersedes advertiser_id; period_from requires period_to), and explaining sort_semantics for slices—all of which exceed the schema's per-field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (search/browse creative families), scopes it to source=meta, and explicitly differentiates from the sibling search_ads for TikTok callers. An agent can distinguish this tool from all siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names when to use this tool vs search_ads (TikTok callers must use search_ads with dedupe=true), names get_media for downloading and add_to_favorites for saving. It also states when NOT to combine filters (country + hub_category or channel) and gives routing guidance for related tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Spytrend tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.