Understanding Dataset Versioning in Braintrust

When Are New Dataset Versions Created?

A new dataset version is created every time an update occurs — that is, whenever a row in the dataset is modified.

All records that belong to the same version share the same transaction ID (_xact_id).

The only exception is when a record is deleted — in that case, it won’t appear in the dataset when fetching all versions.

Viewing Dataset Version History

You can view version history using the API.

If you fetch a dataset without specifying a version filter, you’ll receive all version history.

Example:

curl -X POST "<https://api.braintrust.dev/v1/dataset/{DATASET_ID}/fetch>" \\
  -H "Authorization: Bearer {YOUR_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "limit": 100
  }'

Each dataset row includes a field called _xact_id, which represents the dataset version.

Rows that share the same _xact_id were updated in that same dataset version.

Fetching a Specific Dataset Version

To retrieve the dataset as it existed at a specific version, include the _xact_id in your API request:

curl -X POST "<https://api.braintrust.dev/v1/dataset/{DATASET_ID}/fetch>" \\
  -H "Authorization: Bearer {YOUR_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "version": "{_XACT_ID for specific version}",
    "limit": 10
  }'

This returns the dataset as it existed in that specific version.

Notes on Deleted Records

When you fetch all version history (no version filter), deleted rows won’t appear in the response — they simply disappear from the dataset view.

However, if you filter by a specific version, you will still see the deleted rows as they existed at that point in time.

This is what can make version tracking appear confusing at first glance.

Referencing a Specific Dataset Version

You can reference a specific dataset version when initializing a dataset in the SDK.

Here’s an example:

const dataset = braintrust.initDataset({
  project: "my-project",
  dataset: "my-dataset",
  version: "specific-version-id"  // Pins the dataset to a specific version
});

This allows you to “lock” your dataset to a known state for consistent evaluation and reproducibility.