Scans

Scans iterate a namespace by filter. mode: ids creates an asynchronous job and returns IDs through a results route. mode: count returns one number synchronously.

Routes

Route	Method	Behavior
POST /v2/namespaces/{ns}/scans	POST	Create an ID scan job or return a count.
GET /v2/namespaces/{ns}/scans	GET	List ID scan jobs for the namespace.
GET /v2/namespaces/{ns}/scans/{id}	GET	Read one ID scan job.
GET /v2/namespaces/{ns}/scans/{id}/results	GET	Read completed scan IDs.
DELETE /v2/namespaces/{ns}/scans/{id}	DELETE	Drop the in-memory scan job.

ID Mode

POST /v2/namespaces/products/scans
Content-Type: application/json

{
  "source": "auto",
  "mode": "ids",
  "filters": ["category", "Eq", "Electronics"],
  "page_size": 1000
}

mode defaults to ids. Valid ID-mode sources are auto, cache, and origin.

The create response is 202 Accepted:

{
  "id": "scan-uuid",
  "namespace": "products",
  "source": "auto",
  "effective_source": "origin",
  "status": "running",
  "progress": 0,
  "documents_scanned": 0,
  "created_at": "2026-05-26T10:00:00Z"
}

Read IDs after status is completed:

GET /v2/namespaces/products/scans/scan-uuid/results?limit=1000&offset=0

{
  "ids": ["doc-1", "doc-2"],
  "total": 2
}

Count Mode

POST /v2/namespaces/products/scans
Content-Type: application/json

{
  "mode": "count",
  "source": "auto",
  "filters": ["category", "Eq", "Electronics"],
  "timeout_seconds": 30
}

{
  "count": 4210,
  "served_by": "snapshot",
  "snapshot_sha": "3f9e8b21",
  "watermark_ms": 1747300000123,
  "elapsed_ms": 3
}

Count-mode sources are auto, snapshot, cache, and origin. Snapshot reads are eligible only for a single leaf Eq or In filter on a field present in the latest snapshot fields[]. And, Or, Not, range operators, fields absent from the snapshot, and skipped fields fall through under auto and fail with 412 precondition_failed under source: snapshot.

Live count responses include:

{
  "count": 4210,
  "served_by": "origin",
  "bounded": false,
  "timed_out": false,
  "shards_saturated": 0,
  "shards_total": 1,
  "elapsed_ms": 42
}

Auto-Mode Policy

Auto ties cache freshness to the same consistency watermark used by strong-consistent queries. The gateway tracks per-namespace cache_warmed_through, the watermark observed at the end of the last successful origin warm.

Cache state	Watermark state	Action
Empty	any	Run origin and stamp cache_warmed_through.
Populated, cache_warmed_through >= watermark	observed	Serve cache.
Populated, cache_warmed_through < watermark	observed	Serve cache and start a background origin warm.
Populated, no cache_warmed_through yet	observed	Serve cache and start a background origin warm.
Populated	not yet observed	Serve cache.

When cache is used, _hevlayer_upserted_at <= cache_warmed_through is added before the user filter so the scan is a stable warmed view.