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

# Datasets

> Programmatic access to Gentrace datasets

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

## Basic usage

<CodeGroup dropdown>
  ```typescript theme={null}
  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 theme={null}
  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)
  ```
</CodeGroup>

## Overview

The SDK is built by [Stainless](https://stainless.com) 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:

<ResponseField name="id" type="string" required>
  Unique identifier (UUID)
</ResponseField>

<ResponseField name="name" type="string" required>
  Human-readable name for the dataset
</ResponseField>

<ResponseField name="description" type="string">
  Optional description of the dataset's purpose
</ResponseField>

<ResponseField name="pipelineId" type="string" required>
  UUID of the associated pipeline
</ResponseField>

<ResponseField name="archivedAt" type="string">
  Timestamp when archived (null if active)
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  Creation timestamp
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  Last update timestamp
</ResponseField>

## Resource methods

### Create a dataset

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

  ```python theme={null}
  dataset = await datasets.create(
      name="Production feedback - Q1 2025",
      description="Negative user feedback from production",
      pipeline_id="pipeline-uuid",  # or use pipeline_slug
  )
  ```
</CodeGroup>

### Retrieve a dataset

<CodeGroup dropdown>
  ```typescript theme={null}
  const dataset = await datasets.retrieve('dataset-id');
  console.log(dataset.name);
  ```

  ```python theme={null}
  dataset = await datasets.retrieve("dataset-id")
  print(dataset.name)
  ```
</CodeGroup>

### Update a dataset

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

  ```python theme={null}
  dataset = await datasets.update(
      "dataset-id",
      name="Updated dataset name",
      is_archived=False,
      is_golden=True,  # Mark as golden dataset
  )
  ```
</CodeGroup>

### List with filters

<CodeGroup dropdown>
  ```typescript theme={null}
  // Filter by pipeline
  const datasetList = await datasets.list({
    pipelineId: 'pipeline-id',
    archived: false, // Exclude archived datasets
  });
  ```

  ```python theme={null}
  # Filter by pipeline
  dataset_list = await datasets.list(
      pipeline_id="pipeline-id",
      archived=False,  # Exclude archived datasets
  )
  ```
</CodeGroup>

## Relationship with test cases

Datasets contain test cases. To work with test cases within a dataset, use the [test cases SDK](./test-cases):

<CodeGroup dropdown>
  ```typescript theme={null}
  // Get test cases for a dataset
  const testCasesList = await testCases.list({
    datasetId: dataset.id,
  });
  ```

  ```python theme={null}
  from gentrace import test_cases_async

  # Get test cases for a dataset
  test_case_list = await test_cases_async.list(
      dataset_id=dataset.id
  )
  ```
</CodeGroup>

## See also

* [Test Cases](./test-cases) - Working with test cases within datasets
* [Pipelines](./pipelines) - Managing pipelines that contain datasets
* [`evalDataset()`](../evaluation/dataset-tests) - Running evaluations against datasets