> ## Documentation Index
> Fetch the complete documentation index at: https://crushrewards.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog coverage and freshness stats

> Zero-cost aggregate discovery endpoint with catalog coverage, category tree counts, retailer count, and latest priced-data timestamp.



## OpenAPI

````yaml https://api.syntalic.com/openapi.json get /v1/public/stats
openapi: 3.1.0
info:
  title: 'Syntalic — Data Analytics for Agentic Commerce '
  version: 1.0.0
  description: >-
    Competitive pricing data across US and Canadian e-commerce retailers
    (Amazon, Walmart, Target, Best Buy, Home Depot, etc.). Serves price
    comparisons, deal alerts, brand tracking, promotional intelligence, and
    market analytics to AI agents via x402 and MPP micropayments.
  x-guidance: >-
    This API has three endpoint groups organized by use case:


    **Shopper endpoints** ($0.01/query): Use these for price comparisons and
    deal hunting. Start with /v1/shopper/best-price?q=<product> to find the
    cheapest option across retailers. Use
    /v1/shopper/deal-finder?category=<category> to find discounted products. Use
    /v1/shopper/price-drop-alert?q=<product> to check for recent price drops.


    **Marketing endpoints** ($0.01/query): Use these for competitive analysis.
    /v1/marketing/competitive-landscape?category=<category> shows all products
    in a category with pricing. /v1/marketing/brand-tracker?brand=<brand> tracks
    a brand's pricing over time.
    /v1/marketing/share-of-shelf?category=<category> shows brand market share.


    **Analyst endpoints** ($0.02/query): Use these for market-level insights.
    /v1/analyst/inflation?category=<category> shows price trends over time.
    /v1/analyst/price-dispersion?category=<category> shows price spread across
    retailers.


    All endpoints accept an optional 'country' parameter (us or ca, defaults to
    us). Query parameters use 'q' for free-text search and 'category' for
    category-level queries.


    Marketing and analyst responses carry a `meta` block (served_from,
    freshness_seconds, schema_version) for staleness budgeting and a `resolved`
    block describing how the category input was matched against the taxonomy.
    Every response also sends an X-Data-Freshness-Hours header.


    **Free pre-payment rejection:** requests that cannot be served are rejected
    BEFORE any payment challenge — invalid params (400 INVALID_PARAMS),
    retailers that are not serving-eligible (404 RETAILER_NOT_SERVING_ELIGIBLE,
    with the catalog quality status and the serving_eligible_retailers list in
    error.details), and shopper queries that resolve to nothing in the catalog
    (404 NO_RESULTS). You only pay when the API can actually execute your query.
    Retailer values are case-insensitive (amazon == Amazon).
servers:
  - url: https://api.syntalic.com
security: []
paths:
  /v1/public/stats:
    get:
      tags:
        - Public
      summary: Catalog coverage and freshness stats
      description: >-
        Zero-cost aggregate discovery endpoint with catalog coverage, category
        tree counts, retailer count, and latest priced-data timestamp.
      operationId: getPublicStats
      responses:
        '200':
          description: Public catalog stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: object
                    properties:
                      unique:
                        type: integer
                      listings:
                        type: integer
                  categories:
                    type: object
                    properties:
                      total:
                        type: integer
                      leaves:
                        type: integer
                      max_depth:
                        type: integer
                  retailers:
                    type: object
                    properties:
                      total:
                        type: integer
                  brands:
                    type: object
                    properties:
                      total:
                        type: integer
                  observations:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: >-
                          Approximate count of price/stock observations in the
                          serving hot window (planner estimate, refreshed by
                          autovacuum/analyze).
                  last_updated:
                    type: string
                    format: date-time
                    nullable: true
        '500':
          description: Public discovery error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: true
                    additionalProperties: true

````