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

# Experiments

> List, get, create, delete, and list runs of experiments using the Arize Go SDK.

<Note>
  The `experiments` client methods are currently in **ALPHA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

An experiment is a set of task runs over a dataset, optionally scored by one or more evaluators. Each run is a row of user data: the SDK uses `TaskFields` to identify the `example_id` and `output` columns, and `EvaluatorColumns` to remap evaluator-result columns to the `eval.<name>.<field>` wire schema. The `Get`, `Delete`, and `ListRuns` methods accept either an experiment name or an ID — when a name is passed, `Dataset` (name or ID) is required, and `Space` (name or ID) is required when `Dataset` is also a name. Empty experiments are not allowed: `Create` requires at least one run, otherwise it returns `experiments.ErrNoRuns`.

## List Experiments

`List` returns a paginated list of experiments. `Dataset`, when non-empty, accepts a dataset name or ID and restricts results to that dataset; `Space` is required when `Dataset` is a name.

**Signature:**

```go theme={null}
func (c *Client) List(ctx context.Context, req ListRequest) (*ExperimentList, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/experiments"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Experiments.List(context.Background(), experiments.ListRequest{
        Dataset: "your-dataset-name-or-id",
        Space:   "your-space-name-or-id",
        Limit:   25,
    })
    if err != nil {
        var unauthorized *arize.UnauthorizedError
        if errors.As(err, &unauthorized) {
            log.Fatalf("unauthorized: %v", unauthorized)
        }
        log.Fatal(err)
    }

    for _, exp := range resp.Experiments {
        fmt.Printf("%s: %s\n", exp.Id, exp.Name)
    }
}
```

## Get an Experiment

`Get` returns a single experiment, resolving by name or ID. `Dataset` is required when `Experiment` is a name; `Space` is required when `Dataset` is also passed as a name.

**Signature:**

```go theme={null}
func (c *Client) Get(ctx context.Context, req GetRequest) (*Experiment, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/experiments"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    exp, err := client.Experiments.Get(
        context.Background(),
        experiments.GetRequest{
            Experiment: "your-experiment-name-or-id",
            Dataset:    "your-dataset-name-or-id",
            Space:      "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("experiment not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("experiment %s: %s\n", exp.Id, exp.Name)
}
```

## Create an Experiment

`Create` creates a new experiment, resolving the parent dataset by name or ID. Each entry of `Runs` is a row of user data; `TaskFields` names the columns holding the dataset example ID and the task output (both required), and `EvaluatorColumns` optionally renames evaluator result columns to the `eval.<name>.<field>` wire schema. At least one run is required; an empty `Runs` slice returns `experiments.ErrNoRuns` without contacting the server.

**Signature:**

```go theme={null}
func (c *Client) Create(ctx context.Context, req CreateRequest) (*Experiment, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/experiments"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    exp, err := client.Experiments.Create(
        context.Background(),
        experiments.CreateRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
            Name:    "your-experiment-name",
            Runs: []map[string]any{
                {
                    "example_id":      "example-1",
                    "output":          "hello world",
                    "quality_score":   0.9,
                    "quality_label":   "correct",
                },
            },
            TaskFields: experiments.TaskFields{
                ExampleID: "example_id",
                Output:    "output",
            },
            EvaluatorColumns: map[string]experiments.EvaluatorFields{
                "quality": {
                    Score: "quality_score",
                    Label: "quality_label",
                },
            },
        },
    )
    if err != nil {
        if errors.Is(err, experiments.ErrNoRuns) {
            log.Fatal("cannot create experiment without runs")
        }
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("experiment already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    fmt.Printf("created experiment %s\n", exp.Id)
}
```

## Delete an Experiment

`Delete` removes an experiment, resolving by name or ID. `Dataset` is required when `Experiment` is a name; `Space` is required when `Dataset` is also passed as a name. It returns only an error.

**Signature:**

```go theme={null}
func (c *Client) Delete(ctx context.Context, req DeleteRequest) error
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/experiments"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    err = client.Experiments.Delete(
        context.Background(),
        experiments.DeleteRequest{
            Experiment: "your-experiment-name-or-id",
            Dataset:    "your-dataset-name-or-id",
            Space:      "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("no experiment to remove: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}
```

## List Runs

`ListRuns` returns a paginated list of runs for an experiment, resolving the experiment by name or ID. `Dataset` is required when `Experiment` is a name; `Space` is required when `Dataset` is also passed as a name.

**Signature:**

```go theme={null}
func (c *Client) ListRuns(
    ctx context.Context,
    req ListRunsRequest,
) (*ExperimentRunsList, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/experiments"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Experiments.ListRuns(
        context.Background(),
        experiments.ListRunsRequest{
            Experiment: "your-experiment-name-or-id",
            Dataset:    "your-dataset-name-or-id",
            Space:      "your-space-name-or-id",
            Limit:      50,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("experiment not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("loaded %d runs\n", len(resp.ExperimentRuns))
}
```