Spytrend

Search domains and their traffic

search_shops

Read-only

Search domain-level traffic surfaces with commerce and advertising intelligence. A row is a DOMAIN/SUBDOMAIN surface, not necessarily a company or product. visits is a MONTHLY estimate for traffic_as_of (not live traffic); fetched_at is ingestion time. Judge every estimate using traffic_quality, traffic_confidence, traffic_is_small, traffic_is_data_from_ga, traffic_data_status and history. traffic_paid_share is display + paid-search + paid-social share; trust it only when traffic_sources_available=true. visits_growth_pct is latest-vs-previous month PERCENT; min_growth and sort_by=growth only return growth_qualified rows (current cohort, contiguous 3-month window, previous month >=10k, non-small estimate, confidence >=0.60). category is an estimated SITE category and may be missing/wrong; ai_category is Spytrend's AD category and is preferred for ad-market discovery. created_from/to filter domain_created: best available registration date of the REGISTRABLE ROOT, not product/subdomain launch or Spytrend first-seen. The ClickHouse row does not retain whether that date came from the preferred registry lookup or the legacy fallback. traffic_start_max compares the current estimate with the MAXIMUM of both preceding complete months and excludes stale/low-quality windows; combine with traffic_end_min. ads_monthly counts ads first observed by Spytrend (first_parsed_date), and each point has is_complete=false for the open current month. fb_signal is correlation_only, not causal attribution; honest statuses are correlated_growth, ad_growth_ahead, ad_growth_flat_traffic, ad_growth_declining_traffic, traffic_growth_without_fb_growth, stable_or_mixed and insufficient_signal. sort_by=relevance REQUIRES ai_category and is rejected otherwise. Sorts: visits/revenue/growth/ads/rank/backlinks/ai_traffic/products/fb_score/per_ad/relevance. a separate legacy snapshot is kept alongside; never substitute its similarly named traffic fields for the primary visits/traffic_as_of contract. Returns total, has_more and offset. Use get_shop for the full source payload. Saving shops is free. FREE PLAN COUNTS: when the plan's archive window narrows a request, pagination.total_status is "restricted" and meta.plan_window_cutoff names the boundary — the count then describes the window actually searched, NOT the one requested, so a zero means "nothing in the archive window" and never "nothing exists". QUOTA: 1 token per DELIVERED result from your plan balance (free starter: 500 tokens lifetime; paid plans: 40,000/month; short pages auto-refund — you pay only for results you receive). Default page is 20 results = 20 tokens; pass limit (1–200) to size it. get_usage is free. Autonomous agents must be linked to a spytrend account to access data — an unlinked agent gets an actionable connect-your-account refusal (create agent credentials at spytrend.com/settings?tab=ai, or a human claims it by client_id), NOT a server error. Calls are rate-limited per authenticated user (deployment defaults: 60/minute and 1000/hour); a rate-limit refusal is an MCP tool error with structured error.code=rate_limit_exceeded, scope, window and retry_after_seconds. CONCURRENCY: heavy analytical calls (get_trends, search_ads, search_creatives) are admitted ONE AT A TIME per account — fanning out 5-10 of them in parallel does not go faster, it returns admission refusals for all but one. Issue heavy calls sequentially; light lookups (get_ad, get_advertiser, get_usage) are not gated.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	substring search on the normalized domain; URLs are normalized to their host
`limit`	No	max results (default 20; each delivered result costs 1 token).
`saved`	No	saved scope selector. Use saved=all to restrict results to shops saved in ANY favourites folder.
`offset`	No	pagination offset (0-based)
`pixels`	No	comma-separated pixel identifiers to filter by
`country`	No	ISO-2 country code — keep only shops with traffic in this country
`has_ads`	No	true = only shops with at least one ad in the database
`min_ads`	No	minimum number of ads
`socials`	No	comma-separated social-media handle filters
`sort_by`	No	order by: visits (default), revenue, growth, ads, rank, backlinks, ai_traffic, products, fb_score, per_ad or relevance; relevance REQUIRES ai_category and is rejected without it
`category`	No	estimated site-category filter; may be missing or misclassified, so prefer ai_category for ad-market discovery
`platform`	No	commerce platform the site runs on: Shopify, WooCommerce, WordPress, Wix, Squarespace, Magento, PrestaShop or BigCommerce
`fb_status`	No	observed ads/traffic relationship: correlated_growth, ad_growth_ahead, ad_growth_flat_traffic, ad_growth_declining_traffic, traffic_growth_without_fb_growth, stable_or_mixed or insufficient_signal; correlation only
`folder_id`	No	restrict results to shops saved in this favourites folder UUID. Mirrors the /shops folder view.
`created_to`	No	registrable-root registration date on/before YYYY-MM-DD; NOT product/subdomain launch; per-row RDAP/WHOIS-vs-legacy provenance is unavailable
`max_bounce`	No	maximum bounce rate in PERCENT (0-100) — max_bounce=30 keeps only sticky sites, the reason this control exists. The server converts it to the fraction the column stores.
`max_growth`	No	upper end of the traffic-growth range (percent). The /shops panel has BOTH ends; pair it with min_growth for a band such as 10..50.
`max_per_ad`	No	maximum visits-per-ad efficiency
`max_visits`	No	maximum monthly visits
`min_bounce`	No	minimum bounce rate in PERCENT (0-100), matching the visible /shops bounce slider — min_bounce=70 keeps only high-bounce sites. The server converts it to the fraction the column stores.
`min_growth`	No	minimum latest-vs-previous monthly visits growth PERCENT; only current-cohort growth_qualified rows pass (contiguous 3 months, previous >=10k, non-small, confidence >=0.60)
`min_per_ad`	No	minimum visits-per-ad efficiency (traffic / active ads)
`min_visits`	No	minimum monthly visits
`sort_order`	No	sort direction: asc or desc (default desc)
`ai_category`	No	AI category slug the shop's ads belong to (e.g. ecommerce_and_retail)
`min_revenue`	No	minimum estimated monthly revenue (USD)
`shopify_app`	No	Shopify app slug filter (shops using this app)
`created_from`	No	registrable-root registration date on/after YYYY-MM-DD; NOT product/subdomain launch or Spytrend first-seen; per-row RDAP/WHOIS-vs-legacy provenance is unavailable
`has_products`	No	true = only shops with a product catalog in our database
`min_products`	No	minimum number of catalogued products
`shopify_plan`	No	Shopify plan name filter (e.g. Basic, Shopify, Advanced)
`min_backlinks`	No	minimum total backlinks
`shopify_theme`	No	Shopify theme slug filter
`has_ai_traffic`	No	true = only shops receiving AI-referred traffic (ai_traffic_share > 0)
`has_trustpilot`	No	true = only shops with Trustpilot reviews
`country_exclude`	No	ISO-2 country code to exclude from results
`traffic_end_min`	No	latest monthly estimate at traffic_as_of is at least this value; combine with traffic_start_max
`traffic_start_max`	No	maximum allowed baseline traffic, where baseline=max(two complete months before traffic_as_of); stale, low-quality, incomplete and non-contiguous windows are excluded; combine with traffic_end_min
`min_trustpilot_rating`	No	minimum Trustpilot rating (0-5)
`exclude_infrastructure`	No	drop rows that are transit rather than an offer — link shorteners / link-in-bio, app stores and marketplaces, social networks and messengers, ad servers. Every row also carries surface_role (destination \| redirect \| store \| social \| adserver; absent for an ordinary merchant site) so you can filter yourself instead. NOTE: rows are dropped after the page is fetched, so an excluded page can return fewer than limit rows — page on has_more/offset, not on row count.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No
`meta`	No
`error`	No	Present only when isError is true: machine-readable failure. The human explanation stays in content.
`total`	No
`offset`	No
`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.
`has_more`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 25, 2026

addedOutput schema / properties / error

Added value: +{
+  "description": "Present only when isError is true: machine-readable failure. The human explanation stays in content.",
+  "properties": {
+    "code": {
+      "description": "fine-grained, stable failure code (e.g. invalid_arguments, backend_busy)",
+      "type": "string"
+    },
+    "kind": {
+      "description": "failure class: invalid_argument, not_found, permission_denied, unauthenticated, quota_exceeded, rate_limited, temporarily_unavailable, unavailable_until_ready, unsupported, internal",
+      "type": "string"
+    },
+    "message": {
+      "description": "the same human text as content[0]",
+      "type": "string"
+    },
+    "outcome": {
+      "description": "activity-feed outcome class",
+      "type": "string"
+    },
+    "param": {
+      "description": "the request parameter the failure is about, when known",
+      "type": "string"
+    },
+    "retry_after_seconds": {
+      "description": "wait this long before retrying",
+      "type": "integer"
+    },
+    "retryable": {
+      "description": "true when repeating the SAME call can succeed (after retry_after_seconds when present)",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / params

Added value: +{
+  "description": "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.",
+  "properties": {
+    "applied": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "ignored": {
+      "items": {
+        "properties": {
+          "param": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          },
+          "to": {
+            "description": "the parameter it was applied as, when renamed",
+            "type": "string"
+          },
+          "value": {
+            "description": "the value actually applied, when rewritten",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "normalized": {
+      "items": {
+        "properties": {
+          "param": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          },
+          "to": {
+            "description": "the parameter it was applied as, when renamed",
+            "type": "string"
+          },
+          "value": {
+            "description": "the value actually applied, when rewritten",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "data",
-  "total",
-  "has_more",
-  "offset"
-]

Changed1 schema field changedSep 21, 2026

changedInput schema / properties / created_from / description

Previous value: -"registrable-root registration date on/after YYYY-MM-DD; NOT product/subdomain launch or SpyTrend first-seen; per-row RDAP/WHOIS-vs-legacy provenance is unavailable"New value: +"registrable-root registration date on/after YYYY-MM-DD; NOT product/subdomain launch or Spytrend first-seen; per-row RDAP/WHOIS-vs-legacy provenance is unavailable"

First observedSep 2, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already signal a read-only, non-destructive search, but the description goes far beyond them: visits are monthly estimates, fields have trust caveats, growth filters require qualified rows, free-plan pagination can report restricted totals, quota and refund rules are specified, rate-limit errors are structured, and heavy calls are concurrency-gated. This is exceptional behavioral disclosure.

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

Conciseness4/5

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

The description is long, but it front-loads the most important row-level and estimate semantics and uses clear labels for free-plan, quota, rate-limit, and concurrency guidance. A few clauses repeat what the schema already states, but the density is largely justified given the tool's 40 parameters and the number of interpretation caveats an agent must know.

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

Completeness5/5

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

With 40 parameters, an output schema, and only readOnly/openWorld annotations, the description covers everything needed for correct invocation: field semantics, trust signals, pagination, quota costs, free-plan restrictions, auth requirements, rate limits, and concurrency behavior. Nothing material is missing.

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

Parameters3/5

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

Schema coverage is 100%, so the baseline is 3; the parameter descriptions already carry the growth thresholds, created_from/to provenance caveats, traffic_start_max window semantics, and relevance requirement. The description mostly restates those parameter constraints and adds operational or output-level context rather than genuinely new parameter-level meaning.

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?

The description states a specific verb and resource: it searches domain-level traffic surfaces with commerce and advertising intelligence. It also adds a critical scoping distinction—rows are DOMAIN/SUBDOMAIN surfaces, not necessarily companies or products—which separates it from sibling tools at a glance.

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

Usage Guidelines4/5

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

It gives clear context for when to use the tool and explicitly routes agents seeking the full source payload to get_shop. It also surfaces important exclusions such as growth_qualified rows and the relevance-requires-ai_category requirement. It doesn't enumerate comparisons with every search_* sibling, but the resource-level distinction makes that largely unnecessary.

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.