Datasets

🛑Alpha

OpenTelemetry support is currently in alpha and may undergo significant changes.

Datasets

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

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.

Basic usage

TypeScript

typescript
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);
}

Python

python
import os
from gentrace import init, datasets
init(api_key=os.environ["GENTRACE_API_KEY"])
# List datasets
dataset_list = await datasets.list()
# Access the datasets
for dataset in dataset_list.data:
    print(dataset.name)
    print(dataset.description)

Dataset structure

Each dataset contains:

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

Resource methods

Create a dataset

TypeScript

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

Python

python
dataset = await datasets.create(
    name="Production feedback - Q1 2025",
    description="Negative user feedback from production",
    pipeline_id="pipeline-uuid",  # or use pipeline_slug
)

Retrieve a dataset

TypeScript

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

Python

python
dataset = await datasets.retrieve("dataset-id")
print(dataset.name)

Update a dataset

TypeScript

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

Python

python
dataset = await datasets.update(
    "dataset-id",
    name="Updated dataset name",
    is_archived=False,
    is_golden=True,  # Mark as golden dataset
)

List with filters

TypeScript

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

Python

python
# Filter by pipeline
dataset_list = await datasets.list(
    pipeline_id="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:

TypeScript

typescript
// Get test cases for a dataset
const testCasesList = await testCases.list({
  datasetId: dataset.id
});

Python

python
# Get test cases for a dataset
test_case_list = await test_cases.list(
    dataset_id=dataset.id
)

See also

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