APIClaw

openapi_v2_markets_search

Function

Find a paginated list of US Amazon category markets. Each data[] row contains the category identity and current market measures grouped by statistical scope. data[].marketTotal contains full-category measures; data[].marketSample contains selected Top 100 sales, per-product averages and competition. productTopNMetrics[] and brandTopNMetrics[] each have one row for N=3/5/10/20. Both return avgBsr, avgMonthlySales, avgMonthlyRevenue, monthlySales, monthlyRevenue, monthlySalesRate and monthlyRevenueRate. Product rows also return productTopN and topNSkuCount; brand rows return brandTopN and topNBrandCount. Each row selects the leading products or brands by monthly unit sales; productTopN and brandTopN are rank cutoffs, topNSkuCount is the actual number of selected products, and topNBrandCount is the actual number of selected brands. Brand averages are per product in the selected brands. Both statistical scopes return newProductMetrics[] for 1/3/6/12 calendar-month windows. marketTotal returns new-SKU count, share of all category SKUs, monthly sales, and monthly revenue for each window; marketSample additionally returns averages and shares. meta.total is the number of matching markets.

Use cases

Use search to compare markets by size, per-product sales, price, BSR, package weight or volume, ratings, gross margin, fulfillment, new-product performance or Top N concentration in one call. All filters apply before pagination. topN selects the group used by generic Top N filters; newProductPeriod selects the window used by generic new-product filters and sorting. Neither selector limits the response arrays. Sample sales and revenue filters use per-product averages so markets with different actual sample counts remain comparable. Use category.ids to select multiple market rows by category ID. category.includeDescendantCategoryProducts controls whether each row's product metrics include descendant categories and defaults to true. Alternatively, use a complete category.path or exact category.name; omit all locators to search every market. category.name filters by the exact node name and may return multiple market IDs. For fuzzy category discovery, use /categories. Use structure-profile for its distributions or history for its time series.

Example

Call with {"category":{"ids":["1045564","1234567"],"includeDescendantCategoryProducts":true},"filters":{"sampleAvgMonthlySalesMin":1500,"sampleAvgGrossMarginRateMin":0.2,"topNProductMonthlySalesRateMax":0.5},"sampleType":"unitSalesTop100","topN":"10","newProductPeriod":"3","page":1}. Read data[].categoryId, data[].marketTotal.monthlySales, data[].marketTotal.newProductMetrics[], data[].marketSample.avgMonthlySales, data[].marketSample.productTopNMetrics[], data[].marketSample.brandTopNMetrics[], data[].marketSample.newProductMetrics[] and meta.total.

Data range

US only. Each category ID yields its own market row. By default, its product measures include products assigned directly to the category and its descendants without duplicates; set category.includeDescendantCategoryProducts=false to count only directly assigned products. Top 100 is selected by monthly unit sales or revenue. If date is omitted, the latest available snapshot is used; data[].date gives its actual date. category.path resolves the complete path to one category ID before search; category.name matches the node name exactly. Historical flat requests, including categoryKeyword, remain accepted through Pydantic. New requests use /categories for fuzzy name discovery. Legacy dateRange remains accepted but is not part of the published request schema. Top N and new-product filters use topN and newProductPeriod respectively. Gross-margin rates use decimals from 0 to 1; monetary filters use USD.

New-product definition

For each newProductMetrics[] item with periodMonths=N, a product is new only when its business launch date is later than data.date minus N calendar months and no later than data.date. The business launch date prefers Amazon Date First Available; when unavailable, it uses the earliest valid SKU first-observed date, SKU first-review date, or parent-product first-review date. A missing business launch date is not classified as new; the product still remains in the product-count denominator. Search returns all four windows so an Agent can compare short- and long-window new-product activity without additional calls.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`date`	No	Snapshot lookup date (YYYY-MM-DD); defaults to latest available.
`page`	No	Page number, starting at 1.
`topN`	No	Top group size used by generic Top N filters. The response always returns all four groups.	10
`sortBy`	No	Market metric used for sorting.	sampleMonthlyRevenue
`filters`	No	Market metric conditions, applied before pagination.
`category`	No	Choose IDs, a complete path, or an exact name; omit all locators to search all markets.
`pageSize`	No	Markets per page.
`sortOrder`	No	Sort direction.	desc
`sampleType`	No	Select Top 100 by monthly unit sales or revenue.	unitSalesTop100
`marketplace`	No	Amazon marketplace; currently US only.	US
`newProductPeriod`	No	New-product window used by generic new-product filters and sorting. The response always returns all four windows. For a window of N months, a product is new when its business launch date is later than the snapshot date minus N calendar months and no later than the snapshot date. Products without a business launch date are not counted as new, but remain in the product-count denominator.	3

Schema Changelog

Changes observed during successful MCP inspections.

Changed67 schema fields changedSep 22, 2026

addedInput schema / properties / category

Added value: +{
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "not": {
+        "required": [
+          "ids",
+          "path"
+        ]
+      }
+    },
+    {
+      "not": {
+        "required": [
+          "ids",
+          "name"
+        ]
+      }
+    },
+    {
+      "not": {
+        "required": [
+          "path",
+          "name"
+        ]
+      }
+    }
+  ],
+  "description": "Choose IDs, a complete path, or an exact name; omit all locators to search all markets.",
+  "properties": {
+    "ids": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "maxItems": 100,
+          "minItems": 1,
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Return one market row per Amazon category ID.",
+      "title": "Ids"
+    },
+    "includeDescendantCategoryProducts": {
+      "default": true,
+      "description": "Include descendant-category products in each returned market's metrics and Top 100 sample; defaults to true.",
+      "title": "Includedescendantcategoryproducts",
+      "type": "boolean"
+    },
+    "name": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Exact category-node name; matching names may return multiple markets with different category IDs.",
+      "title": "Name"
+    },
+    "path": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "maxItems": 10,
+          "minItems": 1,
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Full path from root; resolve its last node to one category ID before searching.",
+      "title": "Path"
+    }
+  },
+  "title": "category",
+  "type": "object"
+}

removedInput schema / properties / categoryKeyword

Removed value: -{
-  "description": "Filter by category name keyword (matches any level in category hierarchy, e.g., 'Electronics' or 'Laptops')",
-  "title": "categoryKeyword",
-  "type": "string"
-}

removedInput schema / properties / categoryPath

Removed value: -{
-  "description": "Category hierarchy from root. Example: ['Electronics', 'Computers', 'Laptops'].",
-  "items": {
-    "type": "string"
-  },
-  "title": "categoryPath",
-  "type": "array"
-}

addedInput schema / properties / date

Added value: +{
+  "anyOf": [
+    {
+      "format": "date",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Snapshot lookup date (YYYY-MM-DD); defaults to latest available.",
+  "title": "date",
+  "type": "string"
+}

removedInput schema / properties / dateRange

Removed value: -{
-  "default": "30d",
-  "description": "Aggregation window for metrics like monthly sales, revenue, and rating count. '30d' (default) — last 30 days. 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month.",
-  "title": "dateRange",
-  "type": "string"
-}

addedInput schema / properties / filters

Added value: +{
+  "additionalProperties": false,
+  "description": "Market metric conditions, applied before pagination.",
+  "properties": {
+    "sampleAPlusRateMax": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum share of Top 100 products with A+ content, as a decimal from 0 to 1.",
+      "title": "Sampleaplusratemax"
+    },
+    "sampleAPlusRateMin": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum share of Top 100 products with A+ content, as a decimal from 0 to 1.",
+      "title": "Sampleaplusratemin"
+    },
+    "sampleAmzRateMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample Amazon-sold product rate as decimal.",
+      "title": "Sampleamzratemax"
+    },
+    "sampleAmzRateMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample Amazon-sold product rate as decimal.",
+      "title": "Sampleamzratemin"
+    },
+    "sampleAvgBsrMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample average main-category BSR.",
+      "title": "Sampleavgbsrmax"
+    },
+    "sampleAvgBsrMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample average main-category BSR (lower = better).",
+      "title": "Sampleavgbsrmin"
+    },
+    "sampleAvgGrossMarginRateMax": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample average gross margin rate, from 0 to 1.",
+      "title": "Sampleavggrossmarginratemax"
+    },
+    "sampleAvgGrossMarginRateMin": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample average gross margin rate, from 0 to 1.",
+      "title": "Sampleavggrossmarginratemin"
+    },
+    "sampleAvgMonthlyRevenueMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum estimated monthly revenue per product in the selected Top 100 sample, in USD.",
+      "title": "Sampleavgmonthlyrevenuemax"
+    },
+    "sampleAvgMonthlyRevenueMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum estimated monthly revenue per product in the selected Top 100 sample, in USD.",
+      "title": "Sampleavgmonthlyrevenuemin"
+    },
+    "sampleAvgMonthlySalesMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum estimated monthly unit sales per product in the selected Top 100 sample.",
+      "title": "Sampleavgmonthlysalesmax"
+    },
+    "sampleAvgMonthlySalesMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum estimated monthly unit sales per product in the selected Top 100 sample.",
+      "title": "Sampleavgmonthlysalesmin"
+    },
+    "sampleAvgPackageVolumeMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample average package volume in in³.",
+      "title": "Sampleavgpackagevolumemax"
+    },
+    "sampleAvgPackageVolumeMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample average package volume in in³.",
+      "title": "Sampleavgpackagevolumemin"
+    },
+    "sampleAvgPackageWeightMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample average package weight in oz.",
+      "title": "Sampleavgpackageweightmax"
+    },
+    "sampleAvgPackageWeightMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample average package weight in oz.",
+      "title": "Sampleavgpackageweightmin"
+    },
+    "sampleAvgPriceMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample average price.",
+      "title": "Sampleavgpricemax"
+    },
+    "sampleAvgPriceMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample average price. Example: 10.00.",
+      "title": "Sampleavgpricemin"
+    },
+    "sampleAvgRatingCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample average rating count per product.",
+      "title": "Sampleavgratingcountmax"
+    },
+    "sampleAvgRatingCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample average rating count per product.",
+      "title": "Sampleavgratingcountmin"
+    },
+    "sampleAvgRatingMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample average star rating (0.0–5.0).",
+      "title": "Sampleavgratingmax"
+    },
+    "sampleAvgRatingMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample average star rating (0.0–5.0).",
+      "title": "Sampleavgratingmin"
+    },
+    "sampleAvgSellerCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum average seller count per product in the selected Top 100.",
+      "title": "Sampleavgsellercountmax"
+    },
+    "sampleAvgSellerCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum average seller count per product in the selected Top 100.",
+      "title": "Sampleavgsellercountmin"
+    },
+    "sampleBrandCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample unique brand count.",
+      "title": "Samplebrandcountmax"
+    },
+    "sampleBrandCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample unique brand count.",
+      "title": "Samplebrandcountmin"
+    },
+    "sampleFbaRateMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample FBA product rate as decimal.",
+      "title": "Samplefbaratemax"
+    },
+    "sampleFbaRateMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample FBA product rate as decimal.",
+      "title": "Samplefbaratemin"
+    },
+    "sampleFbmRateMax": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum share of Top 100 products fulfilled by the merchant, as a decimal from 0 to 1.",
+      "title": "Samplefbmratemax"
+    },
+    "sampleFbmRateMin": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum share of Top 100 products fulfilled by the merchant, as a decimal from 0 to 1.",
+      "title": "Samplefbmratemin"
+    },
+    "sampleNewSkuAvgMonthlyRevenueMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum average monthly revenue in USD for new products defined by newProductPeriod.",
+      "title": "Samplenewskuavgmonthlyrevenuemax"
+    },
+    "sampleNewSkuAvgMonthlyRevenueMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum average monthly revenue in USD for new products defined by newProductPeriod.",
+      "title": "Samplenewskuavgmonthlyrevenuemin"
+    },
+    "sampleNewSkuAvgMonthlySalesMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum new product average monthly sales.",
+      "title": "Samplenewskuavgmonthlysalesmax"
+    },
+    "sampleNewSkuAvgMonthlySalesMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum new product average monthly sales.",
+      "title": "Samplenewskuavgmonthlysalesmin"
+    },
+    "sampleNewSkuAvgPriceMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum new product average price.",
+      "title": "Samplenewskuavgpricemax"
+    },
+    "sampleNewSkuAvgPriceMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum new product average price.",
+      "title": "Samplenewskuavgpricemin"
+    },
+    "sampleNewSkuAvgRatingCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum average rating count for new products defined by newProductPeriod.",
+      "title": "Samplenewskuavgratingcountmax"
+    },
+    "sampleNewSkuAvgRatingCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum average rating count for new products defined by newProductPeriod.",
+      "title": "Samplenewskuavgratingcountmin"
+    },
+    "sampleNewSkuAvgRatingMax": {
+      "anyOf": [
+        {
+          "maximum": 5,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum average star rating for new products defined by newProductPeriod.",
+      "title": "Samplenewskuavgratingmax"
+    },
+    "sampleNewSkuAvgRatingMin": {
+      "anyOf": [
+        {
+          "maximum": 5,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum average star rating for new products defined by newProductPeriod.",
+      "title": "Samplenewskuavgratingmin"
+    },
+    "sampleNewSkuCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample new product count.",
+      "title": "Samplenewskucountmax"
+    },
+    "sampleNewSkuCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample new product count.",
+      "title": "Samplenewskucountmin"
+    },
+    "sampleNewSkuRateMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample new product rate as decimal.",
+      "title": "Samplenewskuratemax"
+    },
+    "sampleNewSkuRateMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample new product rate as decimal.",
+      "title": "Samplenewskuratemin"
+    },
+    "sampleSellerCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample unique seller count.",
+      "title": "Samplesellercountmax"
+    },
+    "sampleSellerCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample unique seller count.",
+      "title": "Samplesellercountmin"
+    },
+    "sampleSkuCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum sample SKU count.",
+      "title": "Sampleskucountmax"
+    },
+    "sampleSkuCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum sample SKU count.",
+      "title": "Sampleskucountmin"
+    },
+    "sellerCountry": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Require this seller country code in the Top 100 sample's seller-location list, e.g. US.",
+      "title": "Sellercountry"
+    },
+    "topNBrandMonthlyRevenueRateMax": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum share of sample monthly revenue contributed by the Top N brands selected by topN.",
+      "title": "Topnbrandmonthlyrevenueratemax"
+    },
+    "topNBrandMonthlyRevenueRateMin": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum share of sample monthly revenue contributed by the Top N brands selected by topN.",
+      "title": "Topnbrandmonthlyrevenueratemin"
+    },
+    "topNBrandMonthlySalesRateMax": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum share of sample monthly unit sales contributed by the Top N brands selected by topN.",
+      "title": "Topnbrandmonthlysalesratemax"
+    },
+    "topNBrandMonthlySalesRateMin": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum share of sample monthly unit sales contributed by the Top N brands selected by topN.",
+      "title": "Topnbrandmonthlysalesratemin"
+    },
+    "topNProductMonthlyRevenueRateMax": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum share of sample monthly revenue contributed by the Top N products selected by topN.",
+      "title": "Topnproductmonthlyrevenueratemax"
+    },
+    "topNProductMonthlyRevenueRateMin": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum share of sample monthly revenue contributed by the Top N products selected by topN.",
+      "title": "Topnproductmonthlyrevenueratemin"
+    },
+    "topNProductMonthlySalesRateMax": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum share of sample monthly unit sales contributed by the Top N products selected by topN.",
+      "title": "Topnproductmonthlysalesratemax"
+    },
+    "topNProductMonthlySalesRateMin": {
+      "anyOf": [
+        {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum share of sample monthly unit sales contributed by the Top N products selected by topN.",
+      "title": "Topnproductmonthlysalesratemin"
+    },
+    "totalMonthlyRevenueMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum estimated monthly revenue across all products in the category scope, in USD.",
+      "title": "Totalmonthlyrevenuemin"
+    },
+    "totalMonthlySalesMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum estimated monthly unit sales across all products in the category scope.",
+      "title": "Totalmonthlysalesmin"
+    },
+    "totalSkuCountMax": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Maximum total SKU count in category.",
+      "title": "Totalskucountmax"
+    },
+    "totalSkuCountMin": {
+      "anyOf": [
+        {
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Minimum total SKU count in category.",
+      "title": "Totalskucountmin"
+    }
+  },
+  "title": "filters",
+  "type": "object"
+}

changedInput schema / properties / marketplace / description

Previous value: -"Amazon marketplace code. Only 'US' is currently supported."New value: +"Amazon marketplace; currently US only."

changedInput schema / properties / newProductPeriod / description

Previous value: -"Define 'new product' as listed within X months: '1', '3', '6', or '12'. Affects sampleNewSku* response fields"New value: +"New-product window used by generic new-product filters and sorting. The response always returns all four windows. For a window of N months, a product is new when its business launch date is later than the snapshot date minus N calendar months and no later than the snapshot date. Products without a business launch date are not counted as new, but remain in the product-count denominator."

changedInput schema / properties / page / description

Previous value: -"Page number"New value: +"Page number, starting at 1."

changedInput schema / properties / pageSize / description

Previous value: -"Page size"New value: +"Markets per page."

removedInput schema / properties / sampleAmzRateMax

Removed value: -{
-  "description": "Maximum sample Amazon-sold product rate as decimal.",
-  "minimum": 0,
-  "title": "sampleAmzRateMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAmzRateMin

Removed value: -{
-  "description": "Minimum sample Amazon-sold product rate as decimal.",
-  "minimum": 0,
-  "title": "sampleAmzRateMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgBsrMax

Removed value: -{
-  "description": "Maximum sample average main-category BSR.",
-  "minimum": 0,
-  "title": "sampleAvgBsrMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgBsrMin

Removed value: -{
-  "description": "Minimum sample average main-category BSR (lower = better).",
-  "minimum": 0,
-  "title": "sampleAvgBsrMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgMonthlyRevenueMax

Removed value: -{
-  "description": "Maximum sample average monthly revenue.",
-  "minimum": 0,
-  "title": "sampleAvgMonthlyRevenueMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgMonthlyRevenueMin

Removed value: -{
-  "description": "Minimum sample average monthly revenue. Example: 5000.00.",
-  "minimum": 0,
-  "title": "sampleAvgMonthlyRevenueMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgMonthlySalesMax

Removed value: -{
-  "description": "Maximum sample average monthly sales. Units sold.",
-  "minimum": 0,
-  "title": "sampleAvgMonthlySalesMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgMonthlySalesMin

Removed value: -{
-  "description": "Minimum sample average monthly sales. Units sold. Example: 100.",
-  "minimum": 0,
-  "title": "sampleAvgMonthlySalesMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgPackageVolumeMax

Removed value: -{
-  "description": "Maximum sample average package volume in in³.",
-  "minimum": 0,
-  "title": "sampleAvgPackageVolumeMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgPackageVolumeMin

Removed value: -{
-  "description": "Minimum sample average package volume in in³.",
-  "minimum": 0,
-  "title": "sampleAvgPackageVolumeMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgPackageWeightMax

Removed value: -{
-  "description": "Maximum sample average package weight in oz.",
-  "minimum": 0,
-  "title": "sampleAvgPackageWeightMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgPackageWeightMin

Removed value: -{
-  "description": "Minimum sample average package weight in oz.",
-  "minimum": 0,
-  "title": "sampleAvgPackageWeightMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgPriceMax

Removed value: -{
-  "description": "Maximum sample average price.",
-  "minimum": 0,
-  "title": "sampleAvgPriceMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgPriceMin

Removed value: -{
-  "description": "Minimum sample average price. Example: 10.00.",
-  "minimum": 0,
-  "title": "sampleAvgPriceMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgRatingCountMax

Removed value: -{
-  "description": "Maximum sample average rating count per product.",
-  "minimum": 0,
-  "title": "sampleAvgRatingCountMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgRatingCountMin

Removed value: -{
-  "description": "Minimum sample average rating count per product.",
-  "minimum": 0,
-  "title": "sampleAvgRatingCountMin",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgRatingMax

Removed value: -{
-  "description": "Maximum sample average star rating (0.0–5.0).",
-  "minimum": 0,
-  "title": "sampleAvgRatingMax",
-  "type": "number"
-}

removedInput schema / properties / sampleAvgRatingMin

Removed value: -{
-  "description": "Minimum sample average star rating (0.0–5.0).",
-  "minimum": 0,
-  "title": "sampleAvgRatingMin",
-  "type": "number"
-}

removedInput schema / properties / sampleBrandCountMax

Removed value: -{
-  "description": "Maximum sample unique brand count.",
-  "minimum": 0,
-  "title": "sampleBrandCountMax",
-  "type": "integer"
-}

removedInput schema / properties / sampleBrandCountMin

Removed value: -{
-  "description": "Minimum sample unique brand count.",
-  "minimum": 0,
-  "title": "sampleBrandCountMin",
-  "type": "integer"
-}

removedInput schema / properties / sampleFbaRateMax

Removed value: -{
-  "description": "Maximum sample FBA product rate as decimal.",
-  "minimum": 0,
-  "title": "sampleFbaRateMax",
-  "type": "number"
-}

removedInput schema / properties / sampleFbaRateMin

Removed value: -{
-  "description": "Minimum sample FBA product rate as decimal.",
-  "minimum": 0,
-  "title": "sampleFbaRateMin",
-  "type": "number"
-}

removedInput schema / properties / sampleNewSkuAvgMonthlySalesMax

Removed value: -{
-  "description": "Maximum new product average monthly sales.",
-  "minimum": 0,
-  "title": "sampleNewSkuAvgMonthlySalesMax",
-  "type": "number"
-}

removedInput schema / properties / sampleNewSkuAvgMonthlySalesMin

Removed value: -{
-  "description": "Minimum new product average monthly sales.",
-  "minimum": 0,
-  "title": "sampleNewSkuAvgMonthlySalesMin",
-  "type": "number"
-}

removedInput schema / properties / sampleNewSkuAvgPriceMax

Removed value: -{
-  "description": "Maximum new product average price.",
-  "minimum": 0,
-  "title": "sampleNewSkuAvgPriceMax",
-  "type": "number"
-}

removedInput schema / properties / sampleNewSkuAvgPriceMin

Removed value: -{
-  "description": "Minimum new product average price.",
-  "minimum": 0,
-  "title": "sampleNewSkuAvgPriceMin",
-  "type": "number"
-}

removedInput schema / properties / sampleNewSkuCountMax

Removed value: -{
-  "description": "Maximum sample new product count.",
-  "minimum": 0,
-  "title": "sampleNewSkuCountMax",
-  "type": "integer"
-}

removedInput schema / properties / sampleNewSkuCountMin

Removed value: -{
-  "description": "Minimum sample new product count.",
-  "minimum": 0,
-  "title": "sampleNewSkuCountMin",
-  "type": "integer"
-}

removedInput schema / properties / sampleNewSkuRateMax

Removed value: -{
-  "description": "Maximum sample new product rate as decimal.",
-  "minimum": 0,
-  "title": "sampleNewSkuRateMax",
-  "type": "number"
-}

removedInput schema / properties / sampleNewSkuRateMin

Removed value: -{
-  "description": "Minimum sample new product rate as decimal.",
-  "minimum": 0,
-  "title": "sampleNewSkuRateMin",
-  "type": "number"
-}

removedInput schema / properties / sampleSellerCountMax

Removed value: -{
-  "description": "Maximum sample unique seller count.",
-  "minimum": 0,
-  "title": "sampleSellerCountMax",
-  "type": "integer"
-}

removedInput schema / properties / sampleSellerCountMin

Removed value: -{
-  "description": "Minimum sample unique seller count.",
-  "minimum": 0,
-  "title": "sampleSellerCountMin",
-  "type": "integer"
-}

removedInput schema / properties / sampleSkuCountMax

Removed value: -{
-  "description": "Maximum sample SKU count.",
-  "minimum": 0,
-  "title": "sampleSkuCountMax",
-  "type": "integer"
-}

removedInput schema / properties / sampleSkuCountMin

Removed value: -{
-  "description": "Minimum sample SKU count.",
-  "minimum": 0,
-  "title": "sampleSkuCountMin",
-  "type": "integer"
-}

changedInput schema / properties / sampleType / default

Previous value: -"bySale100"New value: +"unitSalesTop100"

changedInput schema / properties / sampleType / description

Previous value: -"Sampling method for market metrics: 'bySale100' = analyze top 100 products by sales volume, 'byBsr100' = top 100 by BSR rank, 'avg' = category-wide average"New value: +"Select Top 100 by monthly unit sales or revenue."

changedInput schema / properties / sampleType / enum

Previous value: -[
-  "bySale100",
-  "byBsr100",
-  "avg"
-]New value: +[
+  "unitSalesTop100",
+  "revenueTop100",
+  "bySale100",
+  "byRevenue100"
+]

removedInput schema / properties / sampleType / x-unsupported-values
```
Removed value: -[
-  "byBsr100",
-  "avg"
-]
```

changedInput schema / properties / sortBy / default

Previous value: -"sampleAvgMonthlyRevenue"New value: +"sampleMonthlyRevenue"

changedInput schema / properties / sortBy / description

Previous value: -"Sort field (matches response field names)"New value: +"Market metric used for sorting."

changedInput schema / properties / sortBy / enum

Previous value: -[
-  "totalSkuCount",
-  "sampleSkuCount",
-  "sampleAvgPrice",
-  "sampleAvgMonthlySales",
-  "sampleAvgMonthlyRevenue",
-  "sampleTotalMonthlySales",
-  "sampleAvgBsr",
-  "sampleAvgRating",
-  "sampleAvgRatingCount",
-  "sampleBrandCount",
-  "sampleSellerCount",
-  "sampleFbaRate",
-  "sampleNewSkuRate",
-  "topAvgMonthlySales",
-  "topAvgMonthlyRevenue",
-  "topSalesRate",
-  "topBrandSalesRate",
-  "topSellerSalesRate"
-]New value: +[
+  "totalMonthlySales",
+  "totalMonthlyRevenue",
+  "sampleMonthlySales",
+  "sampleMonthlyRevenue",
+  "sampleAvgMonthlySales",
+  "sampleAvgMonthlyRevenue",
+  "totalSkuCount",
+  "sampleSkuCount",
+  "sampleAvgPrice",
+  "sampleTotalMonthlySales",
+  "sampleAvgBsr",
+  "sampleAvgRating",
+  "sampleAvgRatingCount",
+  "sampleBrandCount",
+  "sampleSellerCount",
+  "sampleFbaRate",
+  "sampleNewSkuRate"
+]

changedInput schema / properties / sortOrder / description

Previous value: -"Sort direction: asc or desc"New value: +"Sort direction."

removedInput schema / properties / topAvgBsrMax

Removed value: -{
-  "description": "Maximum Top N average main-category BSR.",
-  "minimum": 0,
-  "title": "topAvgBsrMax",
-  "type": "number"
-}

removedInput schema / properties / topAvgBsrMin

Removed value: -{
-  "description": "Minimum Top N average main-category BSR.",
-  "minimum": 0,
-  "title": "topAvgBsrMin",
-  "type": "number"
-}

removedInput schema / properties / topAvgMonthlyRevenueMax

Removed value: -{
-  "description": "Maximum Top N average monthly revenue.",
-  "minimum": 0,
-  "title": "topAvgMonthlyRevenueMax",
-  "type": "number"
-}

removedInput schema / properties / topAvgMonthlyRevenueMin

Removed value: -{
-  "description": "Minimum Top N average monthly revenue.",
-  "minimum": 0,
-  "title": "topAvgMonthlyRevenueMin",
-  "type": "number"
-}

removedInput schema / properties / topAvgMonthlySalesMax

Removed value: -{
-  "description": "Maximum Top N average monthly sales.",
-  "minimum": 0,
-  "title": "topAvgMonthlySalesMax",
-  "type": "number"
-}

removedInput schema / properties / topAvgMonthlySalesMin

Removed value: -{
-  "description": "Minimum Top N average monthly sales. Units sold.",
-  "minimum": 0,
-  "title": "topAvgMonthlySalesMin",
-  "type": "number"
-}

removedInput schema / properties / topBrandSalesRateMax

Removed value: -{
-  "description": "Maximum Top N brand concentration ratio as decimal.",
-  "minimum": 0,
-  "title": "topBrandSalesRateMax",
-  "type": "number"
-}

removedInput schema / properties / topBrandSalesRateMin

Removed value: -{
-  "description": "Minimum Top N brand concentration ratio as decimal.",
-  "minimum": 0,
-  "title": "topBrandSalesRateMin",
-  "type": "number"
-}

changedInput schema / properties / topN / description

Previous value: -"Number of top products to analyze: '3', '5', '10', or '20'. Affects top* response fields (e.g., topAvgMonthlySales)"New value: +"Top group size used by generic Top N filters. The response always returns all four groups."

removedInput schema / properties / topSalesRateMax

Removed value: -{
-  "description": "Maximum Top N sales share as decimal.",
-  "minimum": 0,
-  "title": "topSalesRateMax",
-  "type": "number"
-}

removedInput schema / properties / topSalesRateMin

Removed value: -{
-  "description": "Minimum Top N sales share as decimal. Example: 0.5 = 50%.",
-  "minimum": 0,
-  "title": "topSalesRateMin",
-  "type": "number"
-}

removedInput schema / properties / topSellerSalesRateMax

Removed value: -{
-  "description": "Maximum Top N seller concentration ratio as decimal.",
-  "minimum": 0,
-  "title": "topSellerSalesRateMax",
-  "type": "number"
-}

removedInput schema / properties / topSellerSalesRateMin

Removed value: -{
-  "description": "Minimum Top N seller concentration ratio as decimal.",
-  "minimum": 0,
-  "title": "topSellerSalesRateMin",
-  "type": "number"
-}

removedInput schema / properties / totalSkuCountMax

Removed value: -{
-  "description": "Maximum total SKU count in category.",
-  "minimum": 0,
-  "title": "totalSkuCountMax",
-  "type": "integer"
-}

removedInput schema / properties / totalSkuCountMin

Removed value: -{
-  "description": "Minimum total SKU count in category.",
-  "minimum": 0,
-  "title": "totalSkuCountMin",
-  "type": "integer"
-}

Changed4 schema fields changedAug 20, 2026
- addedInput schema / properties / marketplace / const
```
Added value: +"US"
```
- changedInput schema / properties / marketplace / description
```
Previous value: -"Amazon marketplace code."New value: +"Amazon marketplace code. Only 'US' is currently supported."
```
- removedInput schema / properties / marketplace / enum
```
Removed value: -[
-  "US",
-  "UK"
-]
```
- removedInput schema / properties / marketplace / x-unsupported-values
```
Removed value: -[
-  "UK"
-]
```

Changed1 schema field changedJun 17, 2026

changedInput schema / properties / dateRange / description

Previous value: -"Aggregation window for metrics like monthly sales, revenue, and rating count. '30d' (default) — last 30 days. 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month.\n\n聚合窗口（月销量、月营收、月评论数等指标）。'30d'（默认）— 最近 30 天。'YYYY-MM' — 该自然月，如 '2026-04'。可选月份：'2026-02' 至最近一个已完结的月份。"New value: +"Aggregation window for metrics like monthly sales, revenue, and rating count. '30d' (default) — last 30 days. 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month."

Changed1 schema field changedJun 3, 2026

changedInput schema / properties / dateRange / description

Previous value: -"Time range filter. Relative ('30d') or month ('2026-02')."New value: +"Aggregation window for metrics like monthly sales, revenue, and rating count. '30d' (default) — last 30 days. 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month.\n\n聚合窗口（月销量、月营收、月评论数等指标）。'30d'（默认）— 最近 30 天。'YYYY-MM' — 该自然月，如 '2026-04'。可选月份：'2026-02' 至最近一个已完结的月份。"

Changed1 schema field changedMay 17, 2026
- changedInput schema / properties / pageSize / description
```
Previous value: -"Page size (max 100)"New value: +"Page size"
```
First observedApr 16, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description carries the full burden, and it delivers: it explains pagination, filter-before-pagination, Top 100 selection by sales/revenue, response always includes all Top N groups, new-product window semantics, date default, descendant inclusion default, and legacy parameter acceptance. This far exceeds what an agent needs for safe invocation.

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 is explicitly sectioned (Function, Use cases, Example, Data range, New-product definition) and front-loaded with the core function. Some redundancy with schema descriptions exists, but the structured format lets agents skip to relevant sections, so the length is largely justified; a small trim would move this to 5.

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?

For a tool with 11 parameters, nested objects, no output schema, and no annotations, the description is exceptionally complete: it describes returned data structures (marketTotal, marketSample, productTopNMetrics, brandTopNMetrics, newProductMetrics, meta.total), pagination, defaults, and edge cases like products without launch dates. An agent has enough to call it correctly and interpret results.

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

Parameters5/5

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

Although the schema already has 100% parameter coverage, the description adds crucial semantics: sample filters operate on per-product averages, category.path resolves to one ID while category.name may match multiple IDs, legacy dateRange/categoryKeyword remain accepted via Pydantic, and gross-margin rates are decimals 0-1 while monetary values are USD. These clarifications materially reduce misuse.

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 opens with 'Find a paginated list of US Amazon category markets', a specific verb+resource+scope, and later contrasts itself with sibling tools like /categories, markets_structure_profile, and markets_history for fuzzy discovery, distributions, and time series. An agent can immediately distinguish this search tool from related market tools without opening schemas.

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?

Section 2 explicitly lists when to use search versus /categories for fuzzy discovery, structure-profile for distributions, and history for time series. It also explains locator alternatives (ids, path, name, or omit all) and notes legacy endpoints remain accepted, giving clear when-to-use and when-not-to guidance.

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

All APIClaw 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.

Resources

Need Help?