> ## 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.

# Experiments

> Programmatic access to Gentrace experiments

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

## Basic usage

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

  ```python theme={null}
  import os
  from gentrace import init, experiments

  init(api_key=os.environ["GENTRACE_API_KEY"])

  # List experiments
  experiment_list = await experiments.list()

  # Access the experiments
  for experiment in experiment_list.data:
      print(experiment.name)
      print(experiment.metadata)
  ```
</CodeGroup>

## Overview

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

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

<ResponseField name="name" type="string">
  Optional friendly name for the experiment
</ResponseField>

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

<ResponseField name="metadata" type="object">
  Optional metadata object for custom data
</ResponseField>

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

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

## Resource methods

### Create an experiment

<CodeGroup dropdown>
  ```typescript theme={null}
  const experiment = await experiments.create({
    pipelineId: 'pipeline-uuid',
    name: 'Prompt optimization experiment',
    metadata: {
      model: 'o3',
    },
  });
  ```

  ```python theme={null}
  experiment = await experiments.create(
      pipeline_id="pipeline-uuid",
      name="Prompt optimization experiment",
      metadata={
          "model": "o3",
      }
  )
  ```
</CodeGroup>

### Retrieve an experiment

<CodeGroup dropdown>
  ```typescript theme={null}
  const experiment = await experiments.retrieve('experiment-id');
  console.log(experiment.pipelineId);
  ```

  ```python theme={null}
  experiment = await experiments.retrieve("experiment-id")
  print(experiment.pipeline_id)
  ```
</CodeGroup>

### Update an experiment

<CodeGroup dropdown>
  ```typescript theme={null}
  const experiment = await experiments.update('experiment-id', {
    name: 'Updated experiment name',
    metadata: { version: 2 },
    status: 'EVALUATING',
  });
  ```

  ```python theme={null}
  experiment = await experiments.update(
      "experiment-id",
      name="Updated experiment name",
      metadata={"version": 2},
      status="EVALUATING",
  )
  ```
</CodeGroup>

### List with filters

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

  ```python theme={null}
  # Filter by pipeline
  experiment_list = await experiments.list(
      pipeline_id="pipeline-id",
  )
  ```
</CodeGroup>

## Common usage with experiment()

Experiments are typically created automatically when using the [`experiment()` function](../evaluation/experiments):

<CodeGroup dropdown>
  ```typescript theme={null}
  import { experiment } from 'gentrace';

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

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

  # This automatically creates an experiment
  # Note: When pipeline_id is omitted, it submits to the default pipeline
  @experiment
  async def my_experiment():
      # Your evaluation code here
      pass
  ```
</CodeGroup>

## See also

* [`experiment()` function](../evaluation/experiments) - High-level function for running experiments
* [`evalDataset()`](../evaluation/dataset-tests) - Running evaluations within experiments
* [Pipelines](./pipelines) - Managing pipelines that contain experiments