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

# API Reference

# API Reference

## Accessing the Experiments API

The `ExperimentsClient` is accessible as a property on the main `Basalt` client:

```python theme={null}
from basalt import Basalt

basalt = Basalt(api_key="your-api-key")
experiment = await basalt.experiments.create(
    feature_slug="recommendation-system",
    name="Test Algorithm v2"
)
```

## Methods

### `create_sync`

Creates a new experiment synchronously.

```python theme={null}
basalt.experiments.create_sync(feature_slug: str, name: str) -> Experiment
```

**Parameters:**

* `feature_slug` (str, required): A slug to identify the feature this experiment belongs to (e.g., "qa-model", "recommendation-algo").
* `name` (str, required): A human-readable name for the experiment (e.g., "GPT-4 vs Claude Comparison").

**Returns:**

An `Experiment` object with:

* `id` (str): Unique experiment identifier
* `name` (str): Experiment name
* `feature_slug` (str): Feature identifier
* `created_at` (str): ISO 8601 timestamp of creation

**Raises:**

* `UnauthorizedError`: Invalid or missing API key
* `BadRequestError`: Invalid parameters
* `NetworkError`: Network connectivity issues
* `BasaltAPIError`: Other API errors

**Example:**

```python theme={null}
experiment = basalt.experiments.create_sync(
    feature_slug="qa-system",
    name="Test Claude vs GPT-4"
)
print(f"Experiment {experiment.id} created")
```

### `create` (async)

Creates a new experiment asynchronously.

```python theme={null}
await basalt.experiments.create(feature_slug: str, name: str) -> Experiment
```

Async variant of `create_sync`. Same parameters and return type.

**Example:**

```python theme={null}
experiment = await basalt.experiments.create(
    feature_slug="qa-system",
    name="Test Claude vs GPT-4"
)
```

## Models

### Experiment

Represents a registered experiment.

```python theme={null}
@dataclass(slots=True, frozen=True)
class Experiment:
    id: str                 # Unique identifier
    name: str               # Human-readable name
    feature_slug: str       # Feature slug
    created_at: str         # ISO 8601 timestamp
```

### TraceExperiment

Represents experiment metadata attached to a trace. Used when attaching an experiment to a span.

```python theme={null}
@dataclass(frozen=True, slots=True)
class TraceExperiment:
    id: str                           # Experiment ID (required)
    name: str | None = None           # Optional display name
    feature_slug: str | None = None   # Optional feature slug
```

All fields except `id` are optional. Example:

```python theme={null}
from basalt.types import TraceExperiment
from basalt.observability import start_observe

experiment = TraceExperiment(
    id="exp-123",
    name="GPT-4 vs Claude",
    feature_slug="qa-system"
)

@start_observe(
    feature_slug="qa-system",
    name="Answer Question",
    experiment=experiment
)
def answer_question(question: str):
    ...
```