Read table history

List every version of a table - timestamps, operations, and who made each change.

Every table is a Delta table, so every write is recorded as a numbered version. Reading the history tells you what changed, when, and by whom - and gives you the version number or timestamp you need to diff, time-travel, or roll back.

Before you start

A table that already exists. The examples use the sample table eddytor.sales.orders (the catalog is always eddytor).
Read access to that table - the viewer role is enough.

Read the history

Pass the catalog, schema, and table as separate arguments:

eddytor get history eddytor sales orders

Add --json for machine-readable output you can pipe into jq:

eddytor get history eddytor sales orders --json

GET /v1/for-developers/tables/eddytor/sales/orders/history
Authorization: Bearer edd_live_…

Returns a JSON array of version entries, newest first.

Call the get_table_history tool with the fully-qualified name:

{ "table": "eddytor.sales.orders" }

In an MCP client (Claude, Cursor) just ask: "Show the history of eddytor.sales.orders."

Open the table, then select the History tab. Each row is a version; click one to see its operation and metrics.

What you get back

Each entry describes one committed version:

Field	Meaning
`version`	The version number. `0` is the table's creation; it counts up by one per write.
`timestamp`	When the commit landed (UTC).
`operation`	What happened - `CREATE TABLE`, `MERGE`, `UPDATE`, `DELETE`, `ADD COLUMN`, `UPDATE FIELD METADATA` (a domain change), `OPTIMIZE`, `VACUUM`.
`userName` / `userId`	Who made the change.
`comment`	An optional commit message.
`operationParameters`	The operation's inputs (e.g. the merge predicate).
`operationMetrics`	Row counts and file stats (e.g. `numOutputRows`, `numFiles`).

A typical --json response (newest version first). Row counts live inside operationMetrics, not as a top-level column:

[
  {
    "version": 4,
    "timestamp": "2026-06-22T14:03:11Z",
    "operation": "MERGE",
    "userName": "ada@acme.io",
    "operationParameters": { "predicate": "target.id = source.id" },
    "operationMetrics": { "numOutputRows": "120", "numTargetRowsUpdated": "8" }
  },
  {
    "version": 0,
    "timestamp": "2026-06-18T11:02:18Z",
    "operation": "CREATE TABLE",
    "userName": "ada@acme.io",
    "operationMetrics": { "numOutputRows": "1000" }
  }
]

Verify

The newest entry's version should match the table's current version (shown by eddytor describe table eddytor sales orders). If you just ran a write, you'll see a new top row with the matching operation.

Gotchas

Heads up

Vacuum truncates how far back you can go. History entries persist, but vacuum deletes the underlying data files older than the retention window. You can still see an old version in the history, but you can no longer read or roll back to it once its files are gone - see Vacuum cuts time-travel.

OPTIMIZE and VACUUM are versions too. Maintenance shows up in the history even though it doesn't change your data - don't mistake an OPTIMIZE commit for a data write when picking a rollback target.
Timestamps are UTC. restore takes a UTC ISO-8601 timestamp; read it straight from this list rather than converting to local time.

Diff two versions - see exactly what changed between two entries.
Time-travel: read an earlier state - query the table as of a past version.
Roll back to a version number - reset to a version you found here.
Rollback vs restore - version number vs timestamp.

Before you start

Read the history

What you get back

Verify

Gotchas

Related

On this page