{"uid":"cap_RbqsbNbLWGGKloYREd6Xs","slug":"price-dispersion-3a6c4966","name":"Price Dispersion","description":"Analyze price spread within a category - mean, stddev, coefficient of variation, and percentiles (p10..p90) with IQR outlier exclusion.","url":"https://api.syntalic.com/v1/analyst/price-dispersion","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-18T05:47:56.093Z","served_from":"live","schema_version":"v3","freshness_seconds":82497},"country":"us","std_dev":210.73,"category":"electronics","currency":"USD","excluded":{"below_floor":2,"price_outliers":112,"accessory_or_parts":65,"refurbished_or_used":78},"resolved":{"alternates":[],"category_id":null,"match_source":"slug","category_path":"electronics","match_confidence":1},"avg_price":205.21,"max_price":919,"min_price":5.99,"department":null,"percentiles":{"p10":24.99,"p25":49.99,"p50":129,"p75":299,"p90":539.2},"product_count":889,"outliers_excluded":112,"coeff_of_variation":1.027,"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_2pGbfpTy93g4eSdQzI2ry","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":"Analyzes price spread within a product category, computing mean, standard deviation, coefficient of variation, and percentiles (p10–p90) with IQR-based outlier exclusion.","exampleAgentPrompt":"What does price dispersion look like in the electronics category in the US — give me the mean, standard deviation, and percentile breakdown so I can see how spread out prices are?","exampleUseCases":null,"resultDescription":"Returns statistical price dispersion metrics for the specified category including mean, standard deviation, coefficient of variation, and p10–p90 percentiles, with outliers excluded using IQR filtering. Includes resolved category metadata for round-trip stability.","failureModes":["Category string cannot be resolved to a canonical category_id — returns a 404 or empty resolution","category_id provided does not exist — returns a 404 not found error","Country code is invalid or unsupported — returns a 400 validation error","Insufficient product data in the category for meaningful statistics — returns sparse or null fields","Rate limiting or payment failure — returns 402 or 429 error"],"whenToPreferThis":"Use this endpoint when you need statistical price spread metrics (stddev, CV, percentiles) for a product category rather than a simple average. Prefer this over Category Summary when the key question is pricing variability or distribution shape, not just central tendency. Ideal for competitive analysis tasks where understanding whether a category has tight or loose pricing is critical.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T00:33:44.841Z","isFirstParty":false}