Snapshot Comparison

Catalogian stores every version of your feed 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 vendor update: See all changes introduced by a major feed update
• •Debugging: "When did SKU-1234 last have the old price?" — 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
{
  "tool": "compare_snapshots",
  "arguments": {
    "sourceSlug": "acme-products",
    "snapshotIdA": "snap_03",
    "snapshotIdB": "snap_05"
  }
}

Response:

{
  "comparison": {
    "sourceSlug": "acme-products",
    "snapshotA": "snap_03 (2026-03-17)",
    "snapshotB": "snap_05 (2026-03-19)",
    "newCount": 50,
    "changedCount": 127,
    "deletedCount": 0,
    "unchangedCount": 49823,
    "sampleNewKeys": ["sku-9001", "sku-9002", "sku-9003"],
    "sampleChangedKeys": ["sku-1234", "sku-5678"],
    "sampleDeletedKeys": []
  }
}

Snapshot comparison vs. delta events

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=widget

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

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