filter_categories
Filter Amazon categories by sales, search volume, return rate, and other metrics to find high-potential categories or view detailed metrics for a single category.
Instructions
[Amazon category commercial-metrics filter] Filter categories by dozens of metrics (sales, GMS, search volume, conversion, return rate, price tier, competitor density, …) — or use as a "category detail" endpoint by passing a single categoryId. Use when: user says "find categories worth entering" / "high-sales categories" / "low return-rate categories" / "high search-volume but low competition categories" / "show me all metrics for category X"; category-level blue-ocean hunt; getting the 30+ metric snapshot of one category. Don't use: for niche-level (use filter_niches — finer granularity); for actual products in a category (use list_category_products); for just the readable name (use get_category_paths). Returns: data.items.data[{ id, categoryId, marketplaceId, timeRange, sampleScope, snapshotDate, unitSoldSum, glanceViewsSum, searchVolumeSum, netShippedGmsSum, buyBoxPriceAvg, buyBoxPriceTier, searchToPurchaseRatio, returnRatio, asinCount, offersPerAsin, newAsinCount, newBrandCount, avgAdSpendPerClick, unitSoldTrendDirection, unitSoldChangeRateBucket, ... trend + quantile-bucket fields }] + data.items.pagination.{ total, page, size, hasNext }. Pagination: use the 'page' param (default 1, 1-based, size capped at 10); 'pagination.hasNext=true' means more pages exist, 'hasNext=false' means last page. Pair with: ↑ required timeRange ('l7d' common) + sampleScope ('all_asin') + marketplaceId (defaults US); categoryId from search_categories / get_category_children; ↓ feed high-potential categories into list_category_products / list_bestsellers for real listings. Cost: ~1 point/page, ~5s. Tips: size capped at 10 (backend hard limit); only paginate when the user explicitly asks for more candidate categories — single-detail or quick-filter calls are fine on page 1; long-tail filter fields (unitSoldTrendDirections / metricChangeRateBuckets / dozens more) pass through via extraFilters.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| marketplaceId | No | Amazon marketplace id. Common: US, UK, DE, JP, FR, IT, ES, CA. Defaults to US. | US |
| timeRange | Yes | Aggregation time range (required). Examples: 'l7d' (last 7 days — verified working). The exact enum is backend-defined; 'l7d' is the safest known value. | |
| sampleScope | Yes | Sample scope (required). Examples: 'all_asin' (all ASINs — verified working). | |
| categoryId | No | When set, returns the full metric row for that single category (this endpoint doubles as the 'detail' endpoint). Omit to list multiple categories matching the filters. Example: '979832011'. | |
| page | No | Page number, 1-based. | |
| size | No | Page size, max 10 (backend hard limit). | |
| sortField | No | Sort field; any response field name is accepted (e.g. 'unitSoldSum', 'netShippedGmsSum'). | |
| sortOrder | No | Sort order: 'asc' or 'desc'. | |
| unitSoldSumMin | No | Min total units sold. | |
| unitSoldSumMax | No | Max total units sold. | |
| netShippedGmsSumMin | No | Min total GMS (gross merchandise sales). | |
| netShippedGmsSumMax | No | Max total GMS. | |
| searchVolumeSumMin | No | Min total search volume. | |
| searchVolumeSumMax | No | Max total search volume. | |
| buyBoxPriceAvgMin | No | Min average buy-box price (marketplace currency). | |
| buyBoxPriceAvgMax | No | Max average buy-box price. | |
| buyBoxPriceTiers | No | Price-tier filter. Allowed: budget, mainstream, premium, luxury. | |
| returnRatioLevels | No | Return-rate quality buckets. Allowed: excellent, average, risk. | |
| searchToPurchaseRatioLevels | No | Search-to-purchase conversion buckets. Allowed: to_improve, average, excellent. | |
| extraFilters | No | Pass-through for any other upstream filter (e.g. unitSoldTrendDirections, newAsinCountLevels, metricChangeRateBuckets). Keys must match the upstream doc verbatim. |