Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

Answers questions like “which of my products are agents and consumers scanning most?” Backed by Closient’s scan analytics, which record every GS1 Digital Link resolution keyed by product, organization, country (derived from IP), and device class. Pre-aggregated daily so date-range queries are fast.

​
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

Brand-scoped. The caller must hold an OAuth token with scope brands:read and membership in the Organization that owns the brand(s) in question. Requests without an organization resolve the caller’s default organization.

​
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
  • Device class — mobile / desktop / tablet / bot
  • Billable vs bot — bot classifier separates automated traffic

​
Not yet available

  • City-level geo (e.g. “most scanned in Austin TX”) — raw ScanEvent records only country_code. A city/metro dimension requires either (a) storing lat/lon at scan time or (b) blending with brand-search-demand which does have lat/lon via SearchEvent. Use brand-search-demand as a proxy for metro-level intent today.
  • 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.
  • brand-search-demand — geographic intent at metro/city level
  • brand-retail-footprint — where your products are actually sold