Skip to main content

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.

When latest_delta.status is "partial", its counts are still growing — take last_complete_delta_id for a number you can act on. The two ids are equal exactly when the newest capture has finished; see Deltas & Changed Rows for the full partial/complete contract.
GET/v1/db-snapshots/sources
GET/v1/db-snapshots/sources/:connectionId

Path parameters

connectionId*uuidThe source connection id, from GET /v1/db-snapshots/sources or your Sources configuration.

curl

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

Response (200) — source with timeline

{
  "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

Error responses

400MASTER_VIEW_WRITEDetail routes cannot be read from the cross-tenant master view ("Snapshots cannot be accessed in master view.").
401unauthorizedMissing or invalid API key.
404RESOURCE_NOT_FOUNDThe connection does not exist in your workspace, or is not a snapshot-capable type (SQL database / Azure Blob CSV folder).

Frequently asked questions

Why can't I trigger a capture through the API?+
Deliberately: capture triggering, cadence configuration, and snapshot deletion stay on the session-authenticated platform surface. Scheduling a scan of your production database is a stronger act than reading its results, and an API key with read scope must never be able to make a source do work.
What does capturing: true actually guarantee?+
That the newest snapshot reports status "capturing" after a staleness check on the worker's heartbeat. It is a strong hint that a capture is running, not cryptographic proof of a live worker — a capture whose worker died reads as failed once the heartbeat goes stale, so a stuck "capturing" never lingers indefinitely.
Why does the newest timeline point sometimes have delta_id: null?+
Three cases: it is the source's first capture (nothing to diff against), the capture is still running (its delta is still being written), or the capture failed and its placeholder delta is withheld rather than served as data. Deltas only become addressable once they represent a real comparison.
What is the difference between snapshot status and delta status?+
A snapshot's status describes the capture job: capturing, ready, or failed. A delta's status describes whether its counts are final: complete when the capture that wrote it reached ready, partial while the capture is still filling it in. A partial delta's counts are a floor, never a result.

Related

Record History
Deltas & Changed Rows
List Sources
Get a Source
Reference Data