> ## 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.

# Brand Scan Summary

> Report a brand's most-scanned products over a time range, with country and device breakdown.

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

```json theme={null}
{
  "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