The datasets SDK provides programmatic access to Gentrace datasets. Datasets organize test cases and are associated with pipelines for evaluation purposes.

​
Basic usage

import { init, datasets } from 'gentrace';

init({
  apiKey: process.env.GENTRACE_API_KEY,
});

// List datasets
const datasetList = await datasets.list();

// Access the datasets
for (const dataset of datasetList.data) {
  console.log(dataset.name);
  console.log(dataset.description);
}

​
Overview

The SDK is built by Stainless and provides type-safe access to Gentrace entities. The datasets object exposes methods to create, retrieve, update, and list datasets.

​
Dataset structure

Each dataset contains:
​
id
string
required
Unique identifier (UUID)
​
name
string
required
Human-readable name for the dataset
​
description
string
Optional description of the dataset’s purpose
​
pipelineId
string
required
UUID of the associated pipeline
​
archivedAt
string
Timestamp when archived (null if active)
​
createdAt
string
required
Creation timestamp
​
updatedAt
string
required
Last update timestamp

​
Resource methods

​
Create a dataset

const dataset = await datasets.create({
  name: 'Production feedback - Q1 2025',
  description: 'Negative user feedback from production',
  pipelineId: 'pipeline-uuid', // or use pipelineSlug
});

​
Retrieve a dataset

const dataset = await datasets.retrieve('dataset-id');
console.log(dataset.name);

​
Update a dataset

const dataset = await datasets.update('dataset-id', {
  name: 'Updated dataset name',
  isArchived: false,
  isGolden: true, // Mark as golden dataset
});

​
List with filters

// Filter by pipeline
const datasetList = await datasets.list({
  pipelineId: 'pipeline-id',
  archived: false, // Exclude archived datasets
});

​
Relationship with test cases

Datasets contain test cases. To work with test cases within a dataset, use the test cases SDK: 
// Get test cases for a dataset
const testCasesList = await testCases.list({
  datasetId: dataset.id
});

​
See also

  • Test Cases - Working with test cases within datasets
  • Pipelines - Managing pipelines that contain datasets
  • evalDataset() - Running evaluations against datasets