Skip to Content
ConceptsScans and snapshots

Scans and snapshots

A scan is the verb; a snapshot is the noun. Every snapshot in Regulatory Snapshot was produced by exactly one scan, and every successful scan produces exactly one snapshot. Knowing the lifecycle that connects them is the single most useful piece of mental furniture for working with the product or the API.

The flow

The shape of the flow is identical whether you start a scan from the dashboard or from POST /v1/scans. Same engine, same output, same snapshot.

Step by step

1. Configure

A scan is parameterised by three things:

  • Jurisdictions — one or more countries or regions. Eleven built-in jurisdictions, plus anything you add as a custom jurisdiction.
  • Regulatory areas — one or more policy domains (AML / KYC, Capital Markets, ESG / Sustainable Finance, …). Ten built-in areas, plus anything you add as a custom area.
  • Time horizon — a forward window in months: 3, 6, 12, 18, 24, or 36.

These three answers are the whole scan request. Everything else (engine variant, model tier, translation languages) has a sensible default; you can override them on either the wizard’s Advanced drawer or the API’s optional request fields.

See Jurisdictions and topics for the conceptual model, or the scan request reference for the wire-level fields.

2. Run

In the app, the Start scan button hands off to the research pipeline. In the API, that is a POST /v1/scans. Two execution modes are available — sync (block for up to 120 seconds and get the snapshot inline) and async (return immediately with a scan_id to poll or stream). The sync mode is the default and covers most one-off scripts; async is what you use for queued or background jobs. See Scans for the detail.

3. Research

The engine fans out across primary regulator sites, supranational standards bodies (BIS, FATF, IOSCO, …) and authoritative secondary commentary. A typical scan with three to five jurisdictions and two to four areas takes 90 seconds to four minutes. Wider scans take longer. While the scan is running:

  • The dashboard shows a toast with live phase progress.
  • The API exposes a polling endpoint (GET /v1/scans/{id}) and a Server-Sent Events stream (GET /v1/scans/{id}/stream) with the same phase events.

4. Synthesise

When the research phase finishes, the engine synthesises the findings into the snapshot envelope — items, trends, executive summary, executive narrative — and edits the prose for clarity. If a comparable previous snapshot exists for the same configuration, a change overlay is produced at this step too. See Changes between scans.

5. Snapshot saved

The snapshot is persisted to your account. From here:

  • Dashboard. Click the View affordance on the scan toast (or open the new entry in My Snapshots). The dashboard loads the snapshot — heatmap, briefing, trends, timeline, sources.
  • API. Read the snapshot at GET /v1/snapshots/{id} or fetch any individual sub-resource.
  • Export. Either flow leads naturally to producing artifacts in Studio (in the app) or via POST /v1/exports (in the API): tearsheets, infographics, audio briefings, slide decks, PDFs.

A simple API sequence

Two writes (POST /v1/scans and POST /v1/exports) and the rest is reads. One snapshot can spawn many exports — a tearsheet, an audio briefing, and a slide deck are three independent export jobs hanging off the same snapshot.

Recurring scans

The pattern most teams settle on is to re-run the same configuration on a cadence — weekly or fortnightly is typical. Each run produces a new snapshot in the same series; from the second run onward, every snapshot includes a change overlay against the previous one. See Changes between scans for what that overlay contains, and What’s changed since last scan for the product walkthrough.

In the app, you can either re-run manually from My Snapshots or set up a scheduled scan in Settings. From the API, schedule the calls from your own orchestration layer — POST /v1/scans is idempotent under the standard Idempotency-Key header, so retries are safe.

What happens if a scan fails

Snapshots only exist for successful scans. If the engine fails partway through, the scan moves to a failed terminal state, no snapshot is produced, and your budget is not charged for the failure. Retry the request — same configuration, same idempotency key — and the engine will run it fresh.

If the scan times out the 120-second sync ceiling, that is not a failure. The API returns a 202 with the scan_id and the scan keeps running in the background; poll or stream until it completes. The eventual snapshot is identical to what a successful sync call would have returned.

What comes next

  • What is a snapshot? — the data model the lifecycle produces.
  • Changes between scans — what re-running a configuration gives you.
  • Your first scan — the product walk-through of step 1 and 2.
  • Scans — the full API reference for the request body, execution modes, and SSE streaming.
What is a snapshot?Changes between scans