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

# List scans

> Recorded scans and their verdicts, newest first.

Scope: `scans:read`. A paginated list (`items`, `total`, `page`, `pageSize`); see
[Requests and responses](https://docs.satyakod.com/api-reference/introduction.md#requests-and-responses).

**range** `string` (default: 7d)

`7d`, `30d` or `90d`: scans from that many days, today included. Not applied with `alert`, which
lists an alert's scans whenever they happened.

**alert** `string`

An alert's id, such as `ALR-2291`: the scans that contributed to it.

**verdict** `string`

`genuine`, `suspicious` or `counterfeit`; several separated by commas (`suspicious,counterfeit`).

**batch** `string`

A batch number, such as `B-1045`.

**product** `string`

A product id, such as `prd_wb18`.

**channel** `string`

`mechanic_app`, `consumer_web`, `whatsapp_bot`, `rugged_handheld`, `mobile_app`, `sdk` or
`field_scanner`.

**sort** `string`

`time`, `verdict`, `product` or `place`; prefix with `-` for descending. Without it, or with any
other value, newest first.

**page** `integer` (default: 1)

**pageSize** `integer` (default: 20)

Up to 200.

Each item:

**id** `string` *required*

Such as `scn_8k2m4q7w1z3x5c9v`, the `scanId` [Verify a serial](https://docs.satyakod.com/api-reference/verify.md) returned.

**scannedAt** `string` *required*

**serial** `string` *required*

**gs1ElementString** `string`

The GS1 element string (`01 <GTIN> 21 <serial>`), for GS1 Signed codes.

**verdict** `string` *required*

`genuine`, `suspicious` or `counterfeit`.

**reason** `string` *required*

Why, in a sentence.

**checks** `object[]` *required*

Each check's `kind`, `result` and `detail`, as [Verify a serial](https://docs.satyakod.com/api-reference/verify.md) returns
them.

**batchId** `string` *required*

The batch number; `—` when the serial isn't from any of your batches.

**productId** `string` *required*

Empty when the product isn't known; `productName` is then "Unknown product".

**codeFamily** `string` *required*

`gs1_signed` or `private_code`.

**channel** `string` *required*

**location** `object`

`district`, `state`, `country` and, when known, `point` (`lat`, `lng`).

**device** `object`

`os` and `appVersion`, when the scanner sent them.

**responseTimeMs** `integer` *required*

**alertId** `string`

The alert this scan contributed to.

Scans by your own staff in the Satyakod app also have `scannedBy` (`id`, `name`, `email`) and
`fieldCheck`, the field audit or goods-in check they were part of.

```bash cURL theme={null}
curl "https://api.satyakod.com/v1/scans?range=30d&verdict=suspicious,counterfeit" \
  -H "Authorization: Bearer $SATYAKOD_KEY"
```

```json 200 theme={null}
{
  "items": [
    {
      "id": "scn_3h7d9k2p5q8r1t4w",
      "scannedAt": "2026-11-12T14:05:31+00:00",
      "serial": "0021-A051-2PXK-20J9",
      "gs1ElementString": "01 08901234567893 21 0021-A051-2PXK-20J9",
      "codeFamily": "gs1_signed",
      "batchId": "B-1045",
      "productId": "prd_wb18",
      "productName": "Wiper blade WB-18",
      "verdict": "suspicious",
      "reason": "Also scanned in Pune 1h 56m earlier",
      "checks": [
        { "kind": "signature", "result": "pass", "detail": "Key acme-gs1-2026-01" },
        { "kind": "serial_status", "result": "pass", "detail": "Issued in B-1045" },
        { "kind": "clone_pattern", "result": "warn", "detail": "Also scanned in Pune 1h 56m earlier" },
        { "kind": "region", "result": "pass", "detail": "Inside authorised region" }
      ],
      "channel": "consumer_web",
      "location": { "district": "Nashik", "state": "MH", "country": "IN" },
      "responseTimeMs": 84,
      "alertId": "ALR-2291"
    }
  ],
  "total": 18,
  "page": 1,
  "pageSize": 20
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.