Delta Events

A delta event is the diff between two consecutive editions of a record. Every scheduled check on a kept record produces one, and so does every revision you ingest by hand, including a check your pipeline triggers itself (see Pipeline-Triggered Ingestion). If nothing changed, the check records a no-change event. If rows moved, you get exact counts and the affected keys, keyed by the record's key field.

Delta event fields

id              string    unique event ID
detectedAt      ISO 8601  when the change was recorded
newCount        int       rows added
changedCount    int       rows modified
deletedCount    int       rows removed
unchangedCount  int       rows that didn't change
totalCount      int       total rows in the new edition
isNoChange      bool      true if nothing changed
newKeys         string[]  added row keys (default first 100)
changedKeys     string[]  changed row keys (default first 100)
deletedKeys     string[]  removed row keys (default first 100)

The key arrays default to 100 keys per category; the REST keysLimit parameter raises that up to 1,000. Full before/after row data (values, not just keys) lives behind the delta rows endpoint: Row Diffs.

Three ways to read a delta

• •Over MCP: your agent calls get_delta and get_delta_rows against the record. See the MCP guide.
• •Over the REST API: list events with GET /v1/sources/:id/delta (cursor pagination, filter by timestamp), read the newest with GET /v1/sources/:id/delta/latest. See the API Reference.
• •By webhook: when a check finds changes, Catalogian POSTs the delta event to your endpoint the moment it is detected. See Webhooks.

Deltas on sampled records

A record holding a free-tier sample diffs within the sample's pinned key set, and the copy stays honest about it. When the whole source was observed, a departed key is a real deletion ("left your catalog"). When the ingest was cut short by the size gate, the event only says rows "fell out of your sample", because a windowed scan cannot know a departure happened. Watching the record unlocks the rest of the file on the next ingest.

Retention

The window applies to delta history only. The record's current rows are never pruned to it; they stay for the life of the record.