> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset changes

> See what each refresh changed since you last looked, correct a value so later refreshes keep it, and put back a row a refresh removed

# Dataset changes

Every write to a dataset is recorded: which refresh run (or person, or one-off
write) made it, which rows it added, which fields it changed from what to what,
and which rows a replace removed. You can read that history, correct a value so
the next refresh does not overwrite it, and put back a row a refresh dropped.

History is kept for 90 days.

## What a change looks like

Changes are grouped into **runs**. A run is one refresh run, or one write no
refresh made (an upload, an agent writing rows, a correction). Each run says who
made it and counts the rows it added, changed and removed, plus the values a
correction kept against it.

Inside a run, each **change** names the row by its key and says what happened:

| Kind | Meaning |
| - | - |
| `added` | A new row. |
| `changed` | One field changed. `old_value` and `new_value` show both sides; a blank cell is `null`. |
| `removed` | A replace left the row out. `old_value` holds the whole row as JSON, which is what Restore puts back. |
| `corrected` | A write sent a different value for a field someone corrected, and the correction was kept. `old_value` is the kept value and `new_value` what the write sent. |
| `handed_back` | Someone handed a correction back to the refresh. |

A row is addressed by its **row key**: the key value for a one-column key, or a
JSON array of the values for a composite key, such as `["acme","2026-11"]`. Each
run names the **key column** its row keys are in; reading one row's history
takes both.

Some writes can only be counted, not compared row by row: appending rows with no
key, replacing a dataset that has no key, and datasets queried live at their
source. Those runs report `field_diffs: false` and a row count, with no changes
listed. One write records at most 50,000 changes; past that the counts stay
exact and the run is marked `truncated`.

## In the app

Open a dataset from **Data**. The panel beside its rows opens on **Changes**:

* **Showing** chooses the period: since you last looked (the default once you
  have looked before), the latest refresh, the last 7 days or the last 30 days.
* Each run is a time, who made it, and its counts. Each change is one line;
  click it to see the old and new values. The row it changed scrolls into view
  and the changed value is highlighted. A run with many changes shows its first
  few, then **Show all**.
* In the rows, every value changed in the period is lightly highlighted, and a
  row added since you last looked has a dot beside it. The table's bar says how
  many changes there are since you last looked.
* A removed row's change has **Restore**.

**Correcting a value.** Open a row, then choose **Correct** beside a field.
Later refreshes keep your value. A corrected value is underlined with dots;
click it to see who corrected it and when, the value before (or the value the
latest refresh sent), and **Restore**, which hands the value back to the
refresh. The corrections refreshes are keeping are listed at the top of Changes
too. Correcting needs the dataset's refresh to write rows by a key, so a row can
be found again; on a dataset without one, **Correct** does not appear.

**Sources.** When a dataset declares where its rows' facts came from (columns
with the `source_url`, `source_quote` and `source_seen_at` roles; see
[Declaring a schema](https://docs.erdo.ai/dataset-schema.md)), the rows show one **Source** column
instead of those columns. Its link opens the source; hovering it shows the quote
and when the source was read. An open row shows its sources at the top.

## Since you last looked

Erdo remembers when you last opened each dataset in the app. Reading that does
not count as a visit; only opening the dataset in the app does, and looks within
30 minutes of each other count as one visit.

```bash theme={null}
erdo datasets last-visit acme.leads
erdo datasets changes acme.leads --since-last-visit
```

`--since-last-visit` starts the list at your `last_viewed_at`. Over MCP or REST,
read the visit and pass `last_viewed_at` as `since`. The app's own Changes panel
starts at `previous_viewed_at`, because opening the dataset has just recorded a
new visit.

Without `--since-last-visit` or `--since`, `changes` covers the last 7 days.

## Reading changes

```bash theme={null}
erdo datasets changes acme.leads                          # the last 7 days, newest run first
erdo datasets changes acme.leads --since 2026-11-03T09:00:00Z
erdo datasets changes acme.leads --run <run-id>           # every change one run made
erdo datasets row-history acme.leads a@example.com --key-column email        # everything that happened to one row
```

Each run lists its first 50 changes. When it made more, the output gives the
`--run <id> --cursor <cursor>` that pages the rest. `--json` prints the raw
result.

## Corrections that refreshes keep

A refresh writes what its source says. When the source is wrong about one
field, correct it and the correction holds: later refreshes that send a
different value keep yours and log a `corrected` change, so you can see the
source still disagrees.

```bash theme={null}
erdo datasets corrections set acme.leads \
  --key-column email --row-key a@example.com \
  --field status --value qualified

erdo datasets corrections set acme.leads \
  --key-column email --row-key a@example.com \
  --field phone --blank                                   # keep the cell empty
```

The value is checked like any other write, so a value the dataset's columns
refuse is refused here too. The row must already exist, and key columns cannot
be corrected. Renaming a column moves its corrections with it; removing the
column, or deleting the row, ends them.

To make a one-off edit the next refresh may overwrite, write the row normally
instead. See [Writing to datasets](https://docs.erdo.ai/dataset-writes.md).

## Restoring a removed row

When a refresh replaces a dataset and leaves a row out, the `removed` change
keeps the whole row. Restore puts it back as it stood, and later replaces keep
it until it is handed back:

```bash theme={null}
erdo datasets row-history acme.leads a@example.com --key-column email        # find the 'removed' change and its id
erdo datasets restore-row acme.leads <change-id>
```

A row that is back in the dataset already is left alone. If the removed row had a value in a column that has since been removed or renamed, it can't be restored as it was, and Restore refuses. A blank cell in such a column is simply left out.

## Handing back

A correction or restored row stays until someone hands it back. Handing back
leaves the current value in place until the next refresh, which may change it,
or remove the row, again.

```bash theme={null}
erdo datasets corrections list acme.leads
erdo datasets corrections hand-back acme.leads <correction-id>
```

## Limits

* Corrections and restores work on **file datasets**, the kind every refresh
  writes. Datasets queried live at a connected database or warehouse keep no
  corrections.
* A managed leads dataset refuses corrections and restores. Correct a lead
  through its lead record, which keeps its own history. Making a dataset a
  managed leads dataset hands back the corrections it held, and each hand-back
  appears in its changes.
* A file you upload to replace a dataset's contents goes in as uploaded. The
  corrections still stand, and the next refresh applies them again.
* To read whole earlier versions of a dataset rather than row-level changes, see
  [Dataset revisions](https://docs.erdo.ai/dataset-revisions.md).

## MCP tools

These tools are in the `datasets` toolset. A connection with the curated list on
does not list them. Add `X-Erdo-MCP-Toolsets: datasets`, or `?toolsets=datasets`
on the MCP URL. See [Toolsets](https://docs.erdo.ai/mcp/overview.md#toolsets).

| Tool | Description |
| - | - |
| `erdo_list_dataset_changes` | List the runs that changed a dataset in a period (`dataset_slug`, `since`, `until`), newest first, each with its first changes. With `change_run_id`, page that run's changes in write order. |
| `erdo_get_dataset_row_history` | Every recorded change to one row (`dataset_slug`, `key_column`, `row_key`), newest first. |
| `erdo_get_dataset_last_visit` | When you last opened the dataset in the app (`last_viewed_at`) and the visit before (`previous_viewed_at`). |
| `erdo_list_dataset_corrections` | The corrected cells and restored rows refreshes are keeping, with their ids. |
| `erdo_correct_dataset_cell` | Correct one field of one row (`key_column`, `row_key`, `field`, `value`; `null` blanks it) and keep it through later refreshes. |
| `erdo_restore_dataset_row` | Put back the row a `removed` change recorded (`change_id`) and keep it. |
| `erdo_hand_back_dataset_correction` | Hand a correction or restored row back to the refresh (`correction_id`). |

## REST

| MCP tool | REST endpoint | Method |
| - | - | - |
| `erdo_list_dataset_changes` | `/v1/datasets/:datasetSlug/changes` | GET (`since`, `until`, `cursor`, `limit`) |
| `erdo_list_dataset_changes` with `change_run_id` | `/v1/datasets/:datasetSlug/changes/:changeRunID/entries` | GET (`cursor`, `limit`) |
| `erdo_get_dataset_row_history` | `/v1/datasets/:datasetSlug/row-history` | GET (`key_column`, `row_key`, `cursor`, `limit`) |
| `erdo_get_dataset_last_visit` | `/v1/datasets/:datasetSlug/last-visit` | GET |
| `erdo_list_dataset_corrections` | `/v1/datasets/:datasetSlug/corrections` | GET |
| `erdo_correct_dataset_cell` | `/v1/datasets/:datasetSlug/corrections` | POST |
| `erdo_hand_back_dataset_correction` | `/v1/datasets/:datasetSlug/corrections/:correctionID/hand-back` | POST |
| `erdo_restore_dataset_row` | `/v1/datasets/:datasetSlug/restore-row` | POST |

```bash theme={null}
# What changed since you last opened the dataset
since=$(curl -s "https://api.erdo.ai/v1/datasets/leads/last-visit" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq -r .last_viewed_at)
curl "https://api.erdo.ai/v1/datasets/leads/changes?since=$since" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Correct a field and keep it
curl -X POST https://api.erdo.ai/v1/datasets/leads/corrections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_column": "email", "row_key": "a@example.com", "field": "status", "value": "qualified"}'

# Put back a removed row
curl -X POST https://api.erdo.ai/v1/datasets/leads/restore-row \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"change_id": 4821}'
```

Corrections and restores record the person whose key made them, and need edit
access to the dataset. Reading changes needs view access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.