Brand Scan Summary

​

When to use

• Brand owner asks about engagement with their catalog.
• “What’s trending in my catalog this month?”
• Triage: “which products deserve better data / images / descriptions?”

​

Auth

​

Endpoint

GET /dashboard/api/v1/brand-analytics/scans
  ?organization_id=<org_id>         # optional; defaults to caller's org
  &brand_id=<brand_id>              # optional; defaults to all brands in org
  &since=<ISO date>                 # default: 30 days ago
  &until=<ISO date>                 # default: today
  &top=<int>                        # default: 20

​

Response

{
  "organization_id": "...",
  "window": {"since": "2026-03-18", "until": "2026-04-17"},
  "total_scans": 14823,
  "billable_scans": 14102,
  "bot_scans": 721,
  "top_products": [
    {
      "gtin": "00012345678905",
      "product_name": "Acme Citric Acid 500g",
      "brand": "Acme",
      "scans": 2104,
      "billable_scans": 2037,
      "by_country": {"US": 1890, "CA": 147, "GB": 67},
      "by_device": {"mobile": 1820, "desktop": 284}
    }
  ],
  "by_country": {"US": 12400, "CA": 1700, "GB": 700, "...": 23},
  "by_day": [{"date": "2026-04-17", "scans": 521}, ...]
}

​

Dimensions available today

• Time — daily rollups via ScanDailySummary
• Country — derived from scan IP
• City / region — ScanEvent.city / ScanEvent.region / ScanEvent.geo are populated for any scan arriving through Cloudflare (CLOUDFLARE_HEADERS_TRUSTED=True in production), and rolled up into ScanDailySummary.by_city / by_region for date-range queries.
• Device class — mobile / desktop / tablet / bot
• Billable vs bot — bot classifier separates automated traffic

​

Not yet available

• Per-hour rollups — tracked in the raw event stream but not yet exposed via the analytics API.

​

Guidance for agents

• Default the window to the last 30 days unless asked otherwise. Longer windows are fine but require the user to be explicit (“since January”).
• Surface both billable and total — high bot_scans on a product can indicate scraper interest worth investigating.
• Pair with brand-retail-footprint when the brand asks “why are my scans lower than expected?” — distribution gaps explain most of it.

​

Related skills

• brand-search-demand — geographic intent at metro/city level
• brand-retail-footprint — where your products are actually sold