Sources & Capture Timeline

List snapshot-capable SQL and blob sources with GET /v1/db-snapshots/sources: capture state, cadence, latest delta, and each source's full capture timeline.

The DB Snapshots surface answers "what changed in my own reference database between two captures". The platform captures point-in-time snapshots of customer SQL databases and Azure Blob folders of CSV exports on a per-source schedule, then computes a delta between consecutive captures — added, modified, and removed rows per table, with before/after values. The /v1 surface reads all of it: sources, timelines, deltas, changed rows, and per-record history.

This surface is read-only by design. Triggering a capture, changing the cadence, and deleting snapshots stay on the session-authenticated platform UI, because scheduling a scan of a customer's production database is not a read-scope act — an API key that can list changes must never be able to make a source do work. Every route here requires only read scope, and every read is tenant-scoped to the key's workspace.

GET /v1/db-snapshots/sources lists the workspace's snapshot-capable connections — SQL databases and CSV blob folders — each with its capture state: how many snapshots exist, whether a capture is running right now (capturing), the newest snapshot and delta, and last_complete_delta_id, the newest delta whose counts are final. The cadence object is a deliberately public subset of the scheduler config (enabled, interval_hours, capture_mode); connection credentials and scan-policy internals never appear on this surface.

GET /v1/db-snapshots/sources/:connectionId adds the source's capture timeline: one point per retained capture with snapshot_id, captured_at, status (capturing, ready, or failed), rows_changed (the total row churn of the delta that ended at this capture), drift (whether that delta detected schema drift), and delta_id. delta_id and rows_changed are null on the first capture — there is no previous snapshot to diff against — and on captures whose delta is not servable, such as a failed capture's placeholder.

capture_mode tells you how a source is captured. On the cadence object it is the configured mode: auto (incremental where the source allows it), full (re-stream every table), or external. On a snapshot it is what that capture actually did: auto, full, incremental, or external. External history is a Postgres-only mode in which the platform captures no rows at all: the source's own change-history table is the record. A sync job walks that history and writes marker snapshots and deltas with per-table counts, and every read of changes or record history goes back to the source's history table. Because the history records when each write happened, change rows and history events from an external source carry an exact changed_at.

curl -s https://api.talonic.com/v1/db-snapshots/sources/8d2f1c4a-6b3e-4f7d-9a1c-5e8b2d4f6a0c \
  -H "Authorization: Bearer tlnc_your_api_key"

{
  "connection_id": "8d2f1c4a-6b3e-4f7d-9a1c-5e8b2d4f6a0c",
  "name": "ERP mirror (Postgres)",
  "engine": "postgres",
  "connection_type": "sql_database",
  "snapshot_count": 14,
  "capturing": false,
  "cadence": { "enabled": true, "interval_hours": 24, "capture_mode": "auto" },
  "latest_snapshot": {
    "id": "3f9a7b1d-2c4e-4a6f-8b0d-1e3c5a7f9b2d",
    "status": "ready",
    "capture_mode": "incremental",
    "captured_at": "2026-08-29T02:00:04.221Z",
    "completed_at": "2026-08-29T02:03:41.508Z",
    "error": null
  },
  "latest_delta": {
    "id": "b4c6e8a0-1d3f-4b5c-9e7a-2f4d6b8c0e1a",
    "status": "complete",
    "computed_at": "2026-08-29T02:03:41.508Z",
    "totals": { "added": 12, "modified": 48, "removed": 3, "tables_touched": 4, "tables_total": 21, "drift": false }
  },
  "last_complete_delta_id": "b4c6e8a0-1d3f-4b5c-9e7a-2f4d6b8c0e1a",
  "timeline": [
    {
      "snapshot_id": "3f9a7b1d-2c4e-4a6f-8b0d-1e3c5a7f9b2d",
      "captured_at": "2026-08-29T02:00:04.221Z",
      "status": "ready",
      "rows_changed": 63,
      "drift": false,
      "delta_id": "b4c6e8a0-1d3f-4b5c-9e7a-2f4d6b8c0e1a"
    },
    {
      "snapshot_id": "9e1c3a5f-7b9d-4e2c-8a4f-6b0d2e4c6a8f",
      "captured_at": "2026-08-28T02:00:03.114Z",
      "status": "ready",
      "rows_changed": null,
      "drift": false,
      "delta_id": null
    }
  ]
}

Errors