Scans and snapshots

A scan is the verb; a snapshot is the noun. Every snapshot was produced by exactly one scan, and every successful scan produces exactly one snapshot. The lifecycle that connects them is the most useful piece of mental furniture in the product, because everything else — readings, exports, change tracking — hangs off its output.

The lifecycle

Queued. The scan has been accepted and is waiting to start. In the app this is visible on the scan toast — the floating progress card that appears when you press Start scan; you can queue several scans and keep working, because a running scan never blocks the dashboard.

Running. The analysis is under way. The toast shows a named phase, a percentage, and a live message as the work advances; the same progress is available to API callers by polling GET /v1/scans/{id} or subscribing to the scan’s event stream. A running scan can be cancelled from its toast (or via the API); cancellation is a terminal state — no snapshot is produced.

Complete. The toast reports Analysis complete with headline counts — changes, trends, jurisdictions — and a View affordance that loads the new snapshot into the dashboard. In the API the scan’s status becomes completed and carries the snapshot_id.

Failed. No snapshot is produced. The scan’s error is shown on the toast and returned by the API. Retrying is simply running the scan again.

The two failure-adjacent points worth internalising: a scan that outlives the API’s 120-second synchronous window is not a failure (it continues in the background and returns 202 with a scan_id to follow), and a cancelled scan leaves no partial snapshot behind — snapshots are all-or-nothing.

What a snapshot fixes in time

A snapshot is a complete, self-contained record of one scan’s findings, stamped with its scan date. Concretely, it fixes:

• The configuration — which jurisdictions, which areas (including custom ones), what horizon. The snapshot’s title is derived from this configuration unless you name it yourself.
• The findings — the items, the typed trends, the executive summary (a bottom line plus priorities) and the long-form executive narrative read on the Briefing tab.
• The sourcing — the scan’s own source index, each source classified by tier, plus the citation audit that ties editorial sentences back to sources. This is what the Sources tab renders.
• Any translations — switch the dashboard into another language and the translated narrative is cached on the snapshot itself, so the next reader gets it instantly.

What a snapshot deliberately does not do is update. Regulators keep publishing after your scan finishes; the snapshot keeps saying what was true on its scan date. The dashboard makes this legible rather than hiding it — the scan date is pinned in the chrome (rendered DD-MM-YYYY) on every tab.

One snapshot, many readings

Loading a snapshot populates every dashboard tab at once. Overview, Analyst Briefing, Trends and Timeline are four projections of the same object — and the likelihood / impact / status filters narrow its items, recomputing every item-derived reading together (the Briefing narrative and Trends ledger are editorial output fixed at scan time and do not re-filter). Nothing on those tabs is fetched from anywhere else; if you can see it, it is in the snapshot. The same is true programmatically: GET /v1/snapshots/{id} returns the full envelope, and the per-part endpoints (items, trends, executive summary, narrative) are conveniences over the same record.

Exports work the same way in the other direction: every artefact generated in Studio or via POST /v1/exports is derived from one named snapshot. One snapshot can spawn any number of artefacts — a tearsheet, a slide deck and a podcast are three independent export jobs hanging off the same record.

Series: the same scan, over time

Re-run an identical scope and the snapshots group into a series. My Snapshots collapses a series into a single ledger row — the newest scan heads the row, and earlier runs slide open beneath it — so ten weekly re-runs read as one tracked scope, not ten unrelated entries. The grouping is by scope alone: the same jurisdictions and the same areas (custom topics included) land in the same series. The engine — and even the horizon — may differ between runs: a 12-month and an 18-month view of the same ground extend one series, because the horizon changes how far you look, not what you are looking at.

Series matter for two reasons:

1. They are the unit of change tracking. The Change Monitor compares the loaded snapshot against the previous scan in its series. A first-of-its-kind scope has no baseline, so its change card can only invite you to re-run it later.
2. They are what scheduled scans produce. A scheduled scan is a saved configuration with a cadence and timezone (and optionally an email notification on completion). Each run lands as a new snapshot extending the series — the Snapshots ledger links a series to the schedule that feeds it.

Where to go next

• Jurisdictions and topics — how to think about the scope you are fixing.
• What “changed” means — what a series buys you from the second run onward.
• Your first scan — the order form walked end-to-end in the product.
• Scans — request fields, execution modes and streaming for API callers.