The experiments SDK provides programmatic access to Gentrace experiments. While typically created via the experiment() function, experiments can also be accessed and managed directly through the SDK.

​
Basic usage

import { init, experiments } from 'gentrace';

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

// List experiments
const experimentList = await experiments.list();

// Access the experiments
for (const experiment of experimentList.data) {
  console.log(experiment.name);
  console.log(experiment.metadata);
}

​
Overview

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

​
Experiment structure

Each experiment contains:
​
id
string
required
Unique identifier (UUID)
​
name
string
Optional friendly name for the experiment
​
pipelineId
string
required
UUID of the associated pipeline
​
metadata
object
Optional metadata object for custom data
​
createdAt
string
required
Creation timestamp
​
updatedAt
string
required
Last update timestamp

​
Resource methods

​
Create an experiment

const experiment = await experiments.create({
  pipelineId: 'pipeline-uuid',
  name: 'Prompt optimization experiment',
  metadata: {
    model: 'o3',
  }
});

​
Retrieve an experiment

const experiment = await experiments.retrieve('experiment-id');
console.log(experiment.pipelineId);

​
Update an experiment

const experiment = await experiments.update('experiment-id', {
  name: 'Updated experiment name',
  metadata: { version: 2 },
  status: 'EVALUATING',
});

​
List with filters

// Filter by pipeline
const experimentList = await experiments.list({
  pipelineId: 'pipeline-id',
});

​
Common usage with experiment()

Experiments are typically created automatically when using the experiment() function: 
import { experiment } from 'gentrace';

// This automatically creates an experiment
experiment(PIPELINE_ID, async () => {
  // Your evaluation code here
});

​
See also