Snapshot Comparison

Catalogian stores every version of your record as a snapshot. The compare_snapshots tool lets you diff any two snapshots, not just consecutive ones, to see what changed between any two points in time.

When to use snapshot comparison

  • •Week-over-week analysis: Compare Monday's snapshot to the previous Monday
  • •Before/after a major update: See all changes introduced by a major data update
  • •Debugging: "When did nc75443737 last change magnitude?" Compare snapshots to narrow it down
  • •Reporting: Generate a summary of net changes over any time period

Listing available snapshots

First, list the snapshots for a source to find the IDs you want to compare:

GET https://api.catalogian.com/v1/sources/:id/snapshots
Authorization: Bearer cat_live_...

Response:

{
  "snapshots": [
    {
      "id": "snap_05",
      "createdAt": "2026-03-19T08:00:00.000Z",
      "totalRows": 50000
    },
    {
      "id": "snap_04",
      "createdAt": "2026-03-18T08:00:00.000Z",
      "totalRows": 49986
    },
    {
      "id": "snap_03",
      "createdAt": "2026-03-17T08:00:00.000Z",
      "totalRows": 49950
    }
  ]
}

Comparing via MCP or Responses API

The compare_snapshots tool is available through both the MCP and OpenAI Responses API endpoints. It computes the diff server-side and returns a summary:

// MCP tool call: compare the two most recent snapshots (the default),
// or pass sinceDate / sinceSnapshotId to pick the older side
{
  "tool": "compare_snapshots",
  "arguments": {
    "recordSlug": "west-coast-earthquakes",
    "sinceSnapshotId": "snap_03"
  }
}

Response:

Comparing snapshots: 2026-03-15T08:00:00.000Z → 2026-03-17T08:00:00.000Z

Added: 5 rows
Removed: 2 rows
Modified: 12 rows

ADDED (5):
  nc75443740: {"id":"nc75443740","mag":1.2,...}
  ...

MODIFIED (12):
  nc75443737:
    before: {"id":"nc75443737","mag":0.75,...}
    after:  {"id":"nc75443737","mag":1.1,...}
  ...

Snapshot comparison vs. delta events

Delta events show changes between consecutive snapshots (snapshot N vs N-1). Snapshot comparison lets you diff any two snapshots (e.g. snapshot 3 vs snapshot 5), aggregating all intermediate changes into a single diff.

Use delta events for real-time change tracking and webhook triggers. Use snapshot comparison for broader analysis across time periods.

Browsing snapshot data

You can also browse the current snapshot row by row, search it, or filter it:

# Browse paginated rows
GET /v1/sources/:id/snapshot-rows?limit=50&cursor=...

# Search across all fields
GET /v1/sources/:id/snapshot-rows?search=Cobb

# Filter by a specific field
GET /v1/sources/:id/snapshot-rows?search=Cobb&field=place

For richer querying (aggregations, distinct values, group-by), use the query_snapshot MCP tool — see MCP Integration.

Understand row-level diffs in detail. Row Diffs →