---
title: "List a dataset version's changes"
method: GET
path: "/v1/datasets/{datasetId}/changes"
---

# List a dataset version's changes

`GET /v1/datasets/{datasetId}/changes`

## Request

- Base URL: `https://api.ploti.ai`
- URL: `https://api.ploti.ai/v1/datasets/{datasetId}/changes`
- Auth: HTTP bearer

The rows a version of a dataset added, changed or removed, so an agent told of a new version (dataset.updated) reads only those instead of the whole dataset. Pass the version the event named; without one it is the latest. An added or changed row of the latest version comes with the row itself (no geometry); a removed row, or one of an older version, comes with its key. When the changes were not recorded (changeLog counts_only, full_refresh or first), the note says so: query the dataset with your own filters instead.

## Path parameters

- `datasetId` string, required

## Query parameters

- `version` integer
- `limit` integer
- `cursor` string

## Response `200`

Done

- object
  - `datasetId` string, required
  - `version` number, required
  - `promotedAt` string, required: When the version went live.
  - `changeLog` 'recorded' | 'counts_only' | 'full_refresh' | 'first', nullable, required: recorded: every change is listed. counts_only: too many to list, counted. full_refresh: not compared. first: the first version. Null: a version from before changes were kept.
  - `counts` object, nullable, required
    - `added` number, required
    - `changed` number, required
    - `removed` number, required
  - `changes` object[], required
    - `kind` 'added' | 'changed' | 'removed', required
    - `key` object, nullable, required: The row's key columns, or for a removed row without a key, its columns.
    - `row` object, nullable, required: The row as it is now, for an added or changed row of the latest version.
  - `nextCursor` string, nullable, required: Pass as cursor for the next page; null on the last.
  - `note` string, nullable, required

## Other responses

- `401`: The credential is missing or not valid.
- `413`: payload_too_large: the body is over 256 KB (2 MB for /v1/tools).
- `415`: unsupported_media_type: a body was sent without Content-Type: application/json.
- `429`: rate_limited: this credential is over its rate. Retry after the Retry-After header's seconds.
- `500`: internal: Ploti failed. Retry; if it keeps happening, contact support.
- `default`: Refused: nothing was done. The code says why and the links say where the person acts on it.

---

[API](https://skmtc.dev/ploti/apis/ploti-api.md) · [All operations](https://skmtc.dev/ploti/apis/ploti-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ploti/apis/ploti-api/revisions/8c2c91c72d52?raw)