DESCRIBE HISTORY: the table's versions, newest first — `version`, `timestamp`, `operation`
const url = 'https://example.com/datanotes/operations/describe_history/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"table":null,"limit":null,"since":null}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/datanotes/operations/describe_history/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "table": null, "limit": null, "since": null }'DESCRIBE HISTORY: the table’s versions, newest first — version, timestamp, operation
(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, …;
EXTERNAL_EDIT = changed outside the engine: an editor, git, sync), operation_metrics and migration_id (undo).
An EXTERNAL_EDIT’s operation_metrics.violations counts the rules this table’s rows break because of the hand edits it holds (each once): the edited rows whose front matter changed and the rows of the table linking to them, a removed or renamed row included (rows of other tables count in their table; a body-only edit is not checked); every rule its rows break when its definition was edited in metastore.yaml. Absent when nothing was checked, or when the edits were logged right before an engine write (the change feed has them); check_table lists the rows invalid now.
Works for dropped tables too (full catalog.schema.table). Use a version with select_rows
(time travel), table_changes or restore_table.
Without table: the history of the whole database — the commits of every table with a log (dropped
ones included), newest first, each with its table (the result’s tables lists the logged tables).
An operation that changed several tables (a cascade, inverse links, restore_database) commits to each
with the same migration_id, and the operations of a batch carry its id as batch: their commits list
in tables every table that operation (or batch) committed to. Pick a moment for restore_database
from it (timestamp, or before_migration with a migration_id or a batch).
limit (default 50) counts commits; since (ISO date or date-time): only commits at or after it.
Authorizations
Section titled “Authorizations”Request Body
Section titled “Request Body”Responses
Section titled “Responses”Done.
object
Qualified table (with table only).
Commits, newest first.
object
Without table: the table of the commit.
ISO date-time of the commit.
E.g. CREATE TABLE, WRITE, UPDATE, DELETE, EXTERNAL_EDIT.
Parameters of the operation.
object
Journal entry of the operation.
object
EXTERNAL_EDIT: the rules this table’s rows break because of the commit’s hand edits; absent when nothing was checked.
Harness / model of the agent (absent for hand edits).
Who made the change.
object
MCP session id.
App running the agent.
Model id reported by the agent.
Tool the agent called.
Credential: owner, or the name of the token that made the request.
Without table: the batch the operation ran in (undo_migration on it reverts the batch).
Without table: every table the same operation (or batch) committed to, when there are several.
Without table: every table with a transaction log (dropped ones included).
Example generated
{ "table": "example", "history": [ { "table": "example", "version": 1, "timestamp": "example", "operation": "example", "operation_parameters": {}, "migration_id": "example", "operation_metrics": { "num_added_files": 1, "num_removed_files": 1, "metadata_changed": true, "violations": 1 }, "engine_info": "example", "user_name": "example", "actor": { "session": "example", "harness": "example", "harness_version": "example", "model": "example", "tool": "example", "auth": "example" }, "batch": "example", "tables": [ "example" ] } ], "tables": [ "example" ]}Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}Missing or wrong bearer token.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}Unknown table, view, migration, note or folder.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}Ambiguous table name: it matches several tables (paths or tables lists them).
object
The tables’ folders the name matches.
The qualified tables the name matches.
Example generated
{ "error": "example", "paths": [ "example" ], "tables": [ "example" ]}Unexpected error.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}