Experiments

The experiments client methods are currently in BETA. The API may change without notice. A one-time warning is emitted on first use.

An experiment is a set of task runs — either run against a dataset or created directly in a space — 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, either Dataset or Space (name or ID) is required to scope the lookup, and Space is also required when Dataset is passed as a name. Empty experiments are not allowed: Create requires at least one run (otherwise experiments.ErrNoRuns) and exactly one of Dataset or Space (otherwise experiments.ErrNoDatasetOrSpace).

List Experiments

List returns a paginated list of experiments, narrowed by whichever scope is given: Dataset (name or ID) returns only experiments run on that dataset; Space (name or ID) returns every experiment in that space, both those associated with a dataset and those without one; passing neither returns every experiment across all spaces the caller can read. Passing both applies the narrower dataset scope, with Space used only to resolve a dataset name. Signature:

func (c *Client) List(ctx context.Context, req ListRequest) (*ListExperiments, error)

Usage Example:

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. Either Dataset or Space is required when Experiment is a name; Space is also required when Dataset is passed as a name. Resolving by Space alone returns arize.AmbiguousNameError when the name matches more than one experiment in that space — pass Dataset or an experiment ID to disambiguate. Signature:

func (c *Client) Get(ctx context.Context, req GetRequest) (*Experiment, error)

Usage Example:

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, either against a dataset or directly in a space. Exactly one of Dataset or Space is required (both accept a name or ID); passing neither returns experiments.ErrNoDatasetOrSpace. Each entry of Runs is a row of user data; TaskFields names the columns holding the task output (required) and the dataset example ID (TaskFields.ExampleID is required only for a dataset-backed experiment), 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:

func (c *Client) Create(ctx context.Context, req CreateRequest) (*Experiment, error)

Usage Example:

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)
}

Append Runs

AppendRuns appends new runs to an existing experiment by ID and returns the updated experiment along with the generated IDs for the inserted runs in input order. Between 1 and 1000 runs may be appended per request; each ExperimentRunInput must include ExampleId and Output. Additional user-defined fields can be set via AdditionalProperties. Signature:

func (c *Client) AppendRuns(
    ctx context.Context,
    req AppendRunsRequest,
) (*ExperimentWithRunIds, error)

Usage Example:

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)
    }

    updated, err := client.Experiments.AppendRuns(
        context.Background(),
        experiments.AppendRunsRequest{
            ExperimentID: "your-experiment-id",
            ExperimentRuns: []experiments.ExperimentRunInput{
                {
                    ExampleId: "example-1",
                    Output:    "hello world",
                    AdditionalProperties: map[string]any{
                        "eval.quality.score": 0.9,
                        "eval.quality.label": "correct",
                    },
                },
            },
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("experiment not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("appended %d runs to experiment %s\n", len(updated.RunIds), updated.Id)
}

Delete an Experiment

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

func (c *Client) Delete(ctx context.Context, req DeleteRequest) error

Usage Example:

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. Either Dataset or Space is required when Experiment is a name; Space is also required when Dataset is passed as a name. Signature:

func (c *Client) ListRuns(
    ctx context.Context,
    req ListRunsRequest,
) (*ListExperimentRuns, error)

Usage Example:

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))
}

Skills

API reference

API clients

List Experiments

Get an Experiment

Create an Experiment

Append Runs

Delete an Experiment

List Runs

​List Experiments

​Get an Experiment

​Create an Experiment

​Append Runs

​Delete an Experiment

​List Runs

List Experiments

Get an Experiment

Create an Experiment

Append Runs

Delete an Experiment

List Runs