{"uid":"cap_JNm4Ic-P2GAM8leLIbVvc","slug":"category-summary-d78bb9f2","name":"Category Summary","description":"High-level category statistics - product/brand/retailer counts, pricing (avg/min/max/median), avg rating, promo rate, in-stock rate, and top brands.","url":"https://api.syntalic.com/v1/analyst/category-summary","method":"GET","headers":{},"bodySchema":{"type":"object","properties":{"country":{"enum":["us","ca"],"type":"string","default":"us","example":"us","description":"Country (us or ca)"},"category":{"type":"string","example":"electronics","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call."},"department":{"type":"string","example":"Electronics","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy."},"category_id":{"type":"integer","example":1,"minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability."}},"additionalProperties":false},"responseSchema":{"type":"object"},"example":{"request":{"country":"us","category":"electronics"},"response":{"meta":{"computed_at":"2026-06-16T17:17:25.887Z","served_from":"live","schema_version":"v3","freshness_seconds":37146},"country":"us","pricing":{"avg":204.26,"max":899.99,"min":5.99,"median":129},"category":"electronics","currency":"USD","excluded":{"below_floor":2,"price_outliers":111,"accessory_or_parts":65,"refurbished_or_used":77},"resolved":{"alternates":[],"category_id":null,"match_source":"slug","category_path":"electronics","match_confidence":1},"avg_rating":null,"department":null,"top_brands":[{"brand":"Sony","product_count":58},{"brand":"Canon","product_count":52},{"brand":"JBL","product_count":37},{"brand":"Amazon","product_count":35},{"brand":"Samsung","product_count":30},{"brand":"Garmin","product_count":24},{"brand":"Soundcore","product_count":18},{"brand":"Panasonic","product_count":17},{"brand":"Kodak","product_count":16},{"brand":"Apple","product_count":16}],"brand_count":324,"product_count":885,"promo_rate_pct":13.3,"retailer_count":6,"in_stock_rate_pct":38.8,"representative_floor":5}},"exampleRequest":{"country":"us","category":"electronics"},"tags":["x402","shopping"],"displayCostAmount":"0.02","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.02/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_xSjXrwnlw3WK2hyv8NXku","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.02","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns high-level statistics for a product category including product/brand/retailer counts, pricing aggregates (avg/min/max/median), average rating, promo rate, in-stock rate, and top brands.","exampleAgentPrompt":"Give me a category summary for electronics in the US — I want to see average, min, max, and median pricing, how many products and brands are listed, the average rating, promo rate, and in-stock rate, and which brands are on top.","exampleUseCases":null,"resultDescription":"A structured object containing aggregate statistics for the resolved category: total product count, brand count, retailer count, pricing stats (average, min, max, median), average customer rating, promotional rate (fraction of products on promo), in-stock rate, and a list of top brands by presence.","failureModes":["Unrecognized category name that fails all four resolver tiers (id, exact name, trigram, embedding kNN) returns an error or empty result","Invalid or unsupported country code (only 'us' and 'ca' are accepted) returns a validation error","category_id not found in database returns a not-found error","Missing both category and category_id with no department provided may return ambiguous or empty results","Rate limiting or payment failure via x402 returns a 402 Payment Required response"],"whenToPreferThis":"Use this endpoint when you need a broad statistical overview of a product category — pricing benchmarks, brand/product counts, availability, and promo rates — rather than individual product details or time-series trends. It is ideal for market sizing, category health checks, or as a first-pass lookup before drilling into competitive landscape or brand tracker endpoints. Prefer this over Price Dispersion when you need multiple metrics at once rather than deep statistical spread analysis.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T12:33:24.149Z","isFirstParty":false}