# Syntalic > Competitive pricing, retail assortment and social intelligence for AI agents, with pay-per-query access via x402 or MPP. - [Introduction](https://syntalic.com/docs/introduction.md): Competitive pricing, assortment and social intelligence for AI agents — pay per query. - [Shelf and social in one question](https://syntalic.com/docs/examples/shelf-and-social.md): Two worked questions that join store listings and social posts through the same ids. - [MCP Server](https://syntalic.com/docs/integrate/mcp.md): Use Syntalic in Claude Code, Cursor, or any MCP-compatible client. - [pay.sh](https://syntalic.com/docs/integrate/pay-sh.md): Use Syntalic from any agent that has the pay CLI attached. - [Direct HTTP](https://syntalic.com/docs/integrate/http.md): Call the API from any backend with an x402 client wrapper. - [Payments overview](https://syntalic.com/docs/payments/overview.md): Two payment protocols, three ways in. - [x402 (USDC)](https://syntalic.com/docs/payments/x402.md): Pay per request in USDC on Solana or Base. - [MPP / Tempo](https://syntalic.com/docs/payments/mpp.md): Pay per request in USDC.e on Tempo via the Machine Payments Protocol. - [Measures](https://syntalic.com/docs/reference/measures.md): Eleven priced paths, one per kind of question. Name the subject, pick the split. - [MCP Tools](https://syntalic.com/docs/reference/mcp-tools.md): What you can ask Syntalic through Claude Code, Cursor, or any MCP client. - [Pricing tiers](https://syntalic.com/docs/reference/pricing.md): Measure and direct-route prices, from $0.01 to $0.05. - [Coverage](https://syntalic.com/docs/reference/coverage.md): Which retailers, which countries, and how fresh the data is. - [Auth & rate limits](https://syntalic.com/docs/reference/auth-and-rate-limits.md): How requests are authenticated and limited. - [Catalog coverage and freshness stats](https://syntalic.com/docs/api-reference/public/catalog-coverage-and-freshness-stats.md): Zero-cost aggregate discovery endpoint with catalog coverage, category tree counts, retailer count, and latest priced-data timestamp. - [Browse public category taxonomy](https://syntalic.com/docs/api-reference/public/browse-public-category-taxonomy.md): Zero-cost aggregate category discovery endpoint. Returns category path nodes and rolled-up listing counts (product_count is retailer listings, not unique products; see grain); row-level product data remains on paid endpoints. - [List retailers (platforms) in the catalog](https://syntalic.com/docs/api-reference/public/list-retailers-platforms-in-the-catalog.md): Zero-cost aggregate discovery endpoint. One row per platform with its served listing count (product_count; see grain), countries seen, and freshest observation; row-level product data remains on paid endpoints. - [List brands in the catalog](https://syntalic.com/docs/api-reference/public/list-brands-in-the-catalog.md): Zero-cost aggregate discovery endpoint. One row per normalized brand with a display label, served listing count (product_count; see grain) and tier; optional q prefix-matches the normalized key (JBL == jbl). The label is the brand's canonical label, the one every other surface prints. Every brand is… - [Search brands and products](https://syntalic.com/docs/api-reference/public/search-brands-and-products.md): Zero-cost discovery search across the whole catalog: brands by name (prefix on the normalized key) and products by title (substring), at most 8 of each. Optional root ranks products filed under that department first; products elsewhere are still found. Each product row carries image_url (the product… - [Catalog coverage map (depth/quality per cell)](https://syntalic.com/docs/api-reference/public/catalog-coverage-map-depthquality-per-cell.md): Zero-cost aggregate discovery endpoint. Coverage + freshness per (platform, country, category_root): priced/recent/known-brand product counts and quality_status (serving/thin/stale — computed from shelf volume and 90-day freshness, never from how the data is acquired), so an agent can gauge whether… - [Find the best price for a product across retailers](https://syntalic.com/docs/api-reference/shopper/find-the-best-price-for-a-product-across-retailers.md): Find the lowest current price for a product across retailers in the US and Canada. Offers are entity-matched (barcode-anchored resolution links the same physical product across stores); each row says so in `match_type` ('entity' is verified, 'title' is a text match that may be a variant). Pass stric… - [Get price history for a product over time](https://syntalic.com/docs/api-reference/shopper/get-price-history-for-a-product-over-time.md): Get historical price observations for a product within a date range. Returns current price, period low/high/avg, trend (rising/falling/stable), good-deal flag, and an observation time-series for charting. Also returns `series`, one row per day at that day's lowest price across the product's entity-m… - [Find discounted products in a category](https://syntalic.com/docs/api-reference/shopper/find-discounted-products-in-a-category.md): Discover discounted in-stock products in a category above a minimum discount threshold (discount = current price below the retailer's list price). Quality-gated: unbranded listings, sub-$5 items, and discounts above 70% (the inflated-list-price spam signature) are excluded. Ranked by discount depth… - [Check for recent price drops on a product](https://syntalic.com/docs/api-reference/shopper/check-for-recent-price-drops-on-a-product.md): Check whether a product's current price is below its rolling average within a configurable lookback window. Returns current price vs. the average across the window plus the lowest-seen price and date. Response field `avg_price_last_30d` is a fixed name for backwards compatibility; the value is alway… - [View all products and pricing in a category](https://syntalic.com/docs/api-reference/marketing/view-all-products-and-pricing-in-a-category.md): View every product and its current pricing within a category across retailers. The default sort is `representative`: rows nearest the category's mean price, so the first page is typical of the shelf and not the cheapest or the dearest. `price_asc` and `price_desc` are explicit. `rating` and `reviews… - [Track a brand's pricing and presence over time](https://syntalic.com/docs/api-reference/marketing/track-a-brands-pricing-and-presence-over-time.md): Track a brand's average/min/max price, product count, in-stock count, and promo count day-by-day across a date range. Brand input matches case-insensitively and across normalization variants (jbl == JBL, tplink == TP-Link). Each point reports insufficient_sample when its basket is under sample_thres… - [Analyze promotional activity in a category](https://syntalic.com/docs/api-reference/marketing/analyze-promotional-activity-in-a-category.md): Analyze promotional activity within a category - promo frequency, average and max discount depth - over a date range. Pivot the breakdown with `aggregate_by`: default `brand` ranks brands within the category; `retailer` ranks retailers across the whole category, or, with `brand=`, on one brand… - [See brand market share within a category](https://syntalic.com/docs/api-reference/marketing/see-brand-market-share-within-a-category.md): Measure each brand's market share within a category by product count. Shows digital shelf dominance. Brand rows are merged across source variants ('JBL'/'jbl', 'TP-Link'/'tplink') with one canonical display label; placeholder brands (null, 'no', 'Generic') are excluded. When the category is one node… - [Analyze a brand's price positioning vs competitors](https://syntalic.com/docs/api-reference/marketing/analyze-a-brands-price-positioning-vs-competitors.md): Place a brand on a category's price ladder. PREFER `tier`: the brand's median current price placed on the shelf's equal-population ladder (entry | value | mid | premium | luxury, so premium always means the shelf's fourth fifth), read from the category's published price band or its nearest banded an… - [Measure out-of-stock rates by retailer or category](https://syntalic.com/docs/api-reference/marketing/measure-out-of-stock-rates-by-retailer-or-category.md): Out-of-stock rate by retail chain or by category root - an on-shelf availability read rather than a pricing one. Answers 'which retailers are running out of stock', 'what is the stockout rate in this category', and 'is my brand actually on shelf'. Pivot with aggregate_by: 'seller' (default) ranks ch… - [Find which retail chains carry a brand or category](https://syntalic.com/docs/api-reference/marketing/find-which-retail-chains-carry-a-brand-or-category.md): Which retail CHAINS carry a brand or a category, ranked by how many distinct priced products each lists, with that chain's average and median price. Answers 'who stocks this brand', 'where can I find it', and 'which retailers carry the most of this category'. Grouped on the retailer chain, never on… - [Break a brand's assortment down by category](https://syntalic.com/docs/api-reference/marketing/break-a-brands-assortment-down-by-category.md): What a brand actually sells: a count of its distinct priced products under each category root, ranked. Answers 'what is this brand's product mix' and 'which categories does it really compete in' - useful before a positioning or shelf question, so the comparison targets the category the brand is dens… - [Rank creators by mention volume in a category](https://syntalic.com/docs/api-reference/social/rank-creators-by-mention-volume-in-a-category.md): Creators ranked by mention volume within a CPG category, with follower tier, reach, organic share and momentum. Answers 'who is talking about this category', 'which creators drive the conversation', 'who is new this window', and with `brand` set 'which creators carry this brand'. `brand` keeps only… - [Share of social conversation by brand](https://syntalic.com/docs/api-reference/social/share-of-social-conversation-by-brand.md): Share of social conversation by brand inside a category, with movement. `mentions` is the event count and is the comparison currency; `views` is view-weighted reach and is reported SEPARATELY. share_pct is computed on mentions, never on views - Instagram stills report no plays, so view-weighting ren… - [Show which subcategories own a category's conversation](https://syntalic.com/docs/api-reference/social/show-which-subcategories-own-a-categorys-conversation.md): Which subcategories own a category's conversation, and how concentrated it is: mentions, share, growth, the leading brand, top-2 concentration, and the share of mentions carried by a single creator. A subcategory is a CHILD node of `category` in the Shopify taxonomy, so send the parent whose split y… - [Rank brands by conversation momentum in a category](https://syntalic.com/docs/api-reference/social/rank-brands-by-conversation-momentum-in-a-category.md): Brands ranked by MOVEMENT in a category's conversation — new entrants first, then the biggest risers and fallers by mention growth. This is the trend view over the same rows brand-share ranks by volume: one dataset, two questions, deliberately not two copies. Each row carries its prior-window base a… - [Emerging conversation topics in a category](https://syntalic.com/docs/api-reference/social/emerging-conversation-topics-in-a-category.md): Emerging and shifting conversation topics inside a category: theme, the product types it spans, post volume, view-weighted reach, growth against the prior window, and a status of new, rising, falling or flat. Topics come from the corpus enrichment's theme extraction — market fact, not a tenant view.… - [Attention by product type within a category](https://syntalic.com/docs/api-reference/social/attention-by-product-type-within-a-category.md): Attention by product type within a category: which types own the conversation and how that mix is shifting. `share_pct` is the type's share of MENTION COUNTS in scope — the same mention-not-view rule every social endpoint holds, because Instagram stills report no plays. Movement fields (growth, is_n… - [Rank the products a category is talking about](https://syntalic.com/docs/api-reference/social/rank-the-products-a-category-is-talking-about.md): The catalog products a category is talking about, ranked by mentions. Every row IS a product the retail catalog carries: `product_key` is the serving entity the mentions resolved to, `product_uid` the listing that stands for it, with the catalog's name, its `url` and its latest US `price_usd` when o… - [Product names read off posts that match no catalog product](https://syntalic.com/docs/api-reference/social/product-names-read-off-posts-that-match-no-catalog-product.md): Product names read off posts that resolved to NO product in the retail catalog: everything product-share leaves out, kept so nothing is lost. Corpus-wide (no `category`). A row is a spelling, not a verified product: `product`, and `brand` for a brand the catalog does not carry, are poster-written st… - [Launches, reviews, stance, retailers and prices posts attach to each brand](https://syntalic.com/docs/api-reference/social/launches-reviews-stance-retailers-and-prices-posts-attach-to-each-brand.md): What posts say about each brand in a category beyond naming it: posts that flag a launch, review it, take a stance on it (the carousel and text stance: positive, negative, neutral, questioning), name a retailer beside it or call one exclusive, quote a price, or place it at an event or in a roundup,… - [Brands creators keep tagging that the catalog does not carry yet](https://syntalic.com/docs/api-reference/social/brands-creators-keep-tagging-that-the-catalog-does-not-carry-yet.md): Brands the tracked creators keep tagging that the retail catalog does not carry yet, ranked by mentions, with creators, reach, movement, first seen, and the Shopify taxonomy paths their products were typed to. This is the one social route with no category: a brand the catalog does not carry has no s… - [Marketing practices creators describe brands using, by shelf](https://syntalic.com/docs/api-reference/social/marketing-practices-creators-describe-brands-using-by-shelf.md): The marketing practices creators who teach marketing describe brands using, per shelf: practices in the closed `marketing-v2` vocabulary (channel > lane > practice: email, retail, supply, brand launch, growth, social, site, branding and customer care), each with the number of creators who described… - [Weekly mentions/views time series for one subject](https://syntalic.com/docs/api-reference/social/weekly-mentionsviews-time-series-for-one-subject.md): Weekly mentions and views time series for one subject — a brand or a category — for charting and modelling. Weeks, not days: the corpus refresh is weekly, and a daily grain would imply precision the pipeline does not have. Coverage counts the WEEKS the series actually has and says so; a 4-week serie… - [Rank brands by share-of-conversation vs share-of-shelf gap](https://syntalic.com/docs/api-reference/social/rank-brands-by-share-of-conversation-vs-share-of-shelf-gap.md): Brands ranked by the GAP between share of social conversation and share of shelf inside one category. Over-indexed attention with under-distribution is the ranging signal a retail buyer wants and the deck slide a challenger brand wants - one endpoint, two customer types. Requires BOTH corpora bound… - [New shelf arrivals vs the conversation around their brand](https://syntalic.com/docs/api-reference/social/new-shelf-arrivals-vs-the-conversation-around-their-brand.md): New shelf arrivals in the window set against the conversation around their brand: which launches landed with traction and which landed in silence. SILENT LAUNCHES ARE RETURNED, FLAGGED - most launches are silent, so filtering them out answers a different and much less useful question. Mentions are B… - [Rank the biggest price movers in a category or brand](https://syntalic.com/docs/api-reference/analyst/rank-the-biggest-price-movers-in-a-category-or-brand.md): Per-product price-change leaderboard: the biggest droppers and gainers in a category or for a brand. Each product's change is LIKE-FOR-LIKE between two matched bands - the best price now versus the best price a window ago - over win = 7, 30 (default) or 90 days, which is the same comparison the Synt… - [Measure how concentrated a category is](https://syntalic.com/docs/api-reference/analyst/measure-how-concentrated-a-category-is.md): How concentrated or fragmented a category is: HHI on the standard 0-10,000 scale, CR4 (the combined share of the four largest brands), the effective number of brands, and a plain-language label. Answers 'is this category competitive or dominated', 'how many real players are there', and 'what is the… - [Analyze price spread across retailers for a category or department](https://syntalic.com/docs/api-reference/analyst/analyze-price-spread-across-retailers-for-a-category-or-department.md): Analyze the spread of current prices within a category - mean, stddev, coefficient of variation, and percentiles (p10..p90) with IQR outlier exclusion. The population is representativeness-filtered: refurbished/used listings, accessory/parts subtrees, and rows under a category-aware price floor are… - [Price index for a specific retailer over time](https://syntalic.com/docs/api-reference/analyst/price-index-for-a-specific-retailer-over-time.md): Compute a normalized price index (retailer avg / category avg) for a specific retailer day-by-day versus its category baseline. Points report insufficient_sample below sample_threshold products plus stable_avg_price over the products priced every day — read trends from the stable series. - [Price band and tiers for a category node](https://syntalic.com/docs/api-reference/analyst/price-band-and-tiers-for-a-category-node.md): The price architecture of one shelf: the comparability window that defines 'similarly priced' there, and the shelf's price tiers. Scoped by ladder NODE (a Shopify taxonomy path like 'electronics/computers'), because a band is a property of one shelf. The window is derived in log space from the shelf… - [High-level summary statistics for a category or department](https://syntalic.com/docs/api-reference/analyst/high-level-summary-statistics-for-a-category-or-department.md): High-level category statistics - product/brand/retailer counts, pricing (avg/min/max/median), promo rate, in-stock rate, and top brands. Headline stats are representativeness-filtered (no refurb/used, no accessory/parts subtrees, category-aware price floor) with exclusion counts disclosed in `exclud… - [Map Amazon browse node ids to GS1 GPC codes](https://syntalic.com/docs/api-reference/reference/map-amazon-browse-node-ids-to-gs1-gpc-codes.md): Map Amazon browse node ids or product-type phrases to GS1 GPC codes. Accepts up to 100 comma-separated browse_id values or q phrases per request (not both). Each browse result carries GPC ancestry, match_precision (SKOS-style), match_source (self | inherited), assurance_state, and browse_node { name… - [Map GS1 GPC codes back to Amazon browse nodes](https://syntalic.com/docs/api-reference/reference/map-gs1-gpc-codes-back-to-amazon-browse-nodes.md): Reverse the crosswalk: given GS1 GPC codes, return the Amazon browse nodes mapped onto them. Accepts up to 100 comma-separated gpc_code values. browse_node_count is the true total per code; browse_ids is capped per code (see ids_per_code_cap in the response) because a coarse segment can carry thousa… - [GS1 GPC attribute schema for one or more bricks](https://syntalic.com/docs/api-reference/reference/gs1-gpc-attribute-schema-for-one-or-more-bricks.md): Return the GPC attribute schema for one or more bricks - attribute names and their allowed value sets. Accepts up to 100 comma-separated gpc_code values. Use this to discover which attributes GS1 defines for a product category (for example Formation, If Organic) and the controlled vocabulary each on… - [Names to ids, across shelves, product types, brands and chains](https://syntalic.com/docs/api-reference/ontology/names-to-ids-across-shelves-product-types-brands-and-chains.md): Send one `term=` per concept. Each comes back as `matches`: every shelf, product type, brand and chain it names (and, with `kinds=entity`, products), each with an `id` you can send to neighbors, coverage and the paid routes (`spt=`, `gpc=`, `brand_id=`). A term that is a hashtag creators write is al… - [What sits next to an id](https://syntalic.com/docs/api-reference/ontology/what-sits-next-to-an-id.md): For a shelf: its ancestors, children and siblings, the product types filed under it, its top brands and chains. For a product type: its ancestry and the shelves it is filed under. For a brand: its profile and aliases, the shelves its products sit on (`footprint`), the chains that carry it and the ch… - [How much evidence stands behind ids, and what was looked at](https://syntalic.com/docs/api-reference/ontology/how-much-evidence-stands-behind-ids-and-what-was-looked-at.md): The denominators of an absence claim: listings, freshness, the channels present and not observed, and the chains scanned. "Not seen at X" may be said only when X is in `retailers_scanned`; a chain outside it is unknown, not absent. `retailer=` asks one brand-and-chain question: seen there, scanned a… - [List the measures (free)](https://syntalic.com/docs/api-reference/measures/list-the-measures-free.md): Free. Every measure with its price, its default split and each `by` split available now: what it answers, the route that answers it, which subject kinds it takes and an example request. No payment and no parameters. - [Who sells one product, and at what price, now.](https://syntalic.com/docs/api-reference/measures/who-sells-one-product-and-at-what-price-now.md): Who sells one product, and at what price, now. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, o… - [The price level and spread of a shelf.](https://syntalic.com/docs/api-reference/measures/the-price-level-and-spread-of-a-shelf.md): The price level and spread of a shelf. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, or a subj… - [How prices moved, for a product, a shelf or a brand.](https://syntalic.com/docs/api-reference/measures/how-prices-moved-for-a-product-a-shelf-or-a-brand.md): How prices moved, for a product, a shelf or a brand. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `… - [Who discounts, how often and how deep.](https://syntalic.com/docs/api-reference/measures/who-discounts-how-often-and-how-deep.md): Who discounts, how often and how deep. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, or a subj… - [What is on the shelf, and who holds it.](https://syntalic.com/docs/api-reference/measures/what-is-on-the-shelf-and-who-holds-it.md): What is on the shelf, and who holds it. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, or a sub… - [Share of social conversation, and how it is moving.](https://syntalic.com/docs/api-reference/measures/share-of-social-conversation-and-how-it-is-moving.md): Share of social conversation, and how it is moving. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `b… - [What posts say, as labels: launches, reviews, stance, names, practices.](https://syntalic.com/docs/api-reference/measures/what-posts-say-as-labels:-launches-reviews-stance-names-practices.md): What posts say, as labels: launches, reviews, stance, names, practices. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` nam… - [Social attention set against the shelf.](https://syntalic.com/docs/api-reference/measures/social-attention-set-against-the-shelf.md): Social attention set against the shelf. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, or a sub… - [A name, phrase or code to ids.](https://syntalic.com/docs/api-reference/measures/a-name-phrase-or-code-to-ids.md): A name, phrase or code to ids. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, or a subject the… - [What sits next to an id.](https://syntalic.com/docs/api-reference/measures/what-sits-next-to-an-id.md): What sits next to an id. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, or a subject the split… - [How much evidence stands behind an id.](https://syntalic.com/docs/api-reference/measures/how-much-evidence-stands-behind-an-id.md): How much evidence stands behind an id. A measure is one metric family asked one way: `by` picks the split, `subject` is what it is about, and every other parameter is the answering route's own. The answer is that route's answer, unchanged, and `X-Syntalic-Preset` names it. An unknown `by`, or a subj… ## OpenAPI Specs - [openapi](https://api.syntalic.com/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.