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

# Migrate Experiments Client

> Migrate experiment methods from ArizeDatasetsClient to ArizeClient.experiments in the v8 SDK.

This section covers migrating experiment methods from v7's `ArizeDatasetsClient` to v8's `ArizeClient.experiments`.

<CodeGroup>
  ```python Version 7 theme={null}
  from arize.experimental.datasets import ArizeDatasetsClient

  # v7 api_key parameter took developer key values
  client = ArizeDatasetsClient(
      api_key="your-developer-key"  # Developer key (deprecated)
  )
  ```

  ```python Version 8 theme={null}
  from arize import ArizeClient

  # v8 api_key parameter takes standard API keys
  client = ArizeClient(
      api_key="your-api-key"  # Standard API key
  )
  ```
</CodeGroup>

## run\_experiment()

The `run_experiment()` method migrates from `client.run_experiment()` to `client.experiments.run()`.

### Parameter Reference

| Parameter                    | v7       | v8         | Changes                                                  |
| ---------------------------- | -------- | ---------- | -------------------------------------------------------- |
| `space_id`                   | Required | ❌ Removed  | Not needed in v8                                         |
| `experiment_name`            | Required | Required   | Renamed to `name`                                        |
| `name`                       | N/A      | ✅ Required | Renamed from `experiment_name`                           |
| `task`                       | Required | Required   | --                                                       |
| `dataset_df`                 | Optional | ❌ Removed  | Dataset downloaded automatically in v8, use `dataset_id` |
| `dataset_id`                 | Optional | Required   | Now required; no longer accepts `dataset_name`           |
| `dataset_name`               | Optional | ❌ Removed  | Use `dataset_id` instead                                 |
| `evaluators`                 | Optional | Optional   | --                                                       |
| `dry_run`                    | Optional | Optional   | --                                                       |
| `dry_run_count`              | N/A      | ✅ Optional | Number of examples to use in dry run (default 10)        |
| `concurrency`                | Optional | Optional   | --                                                       |
| `set_global_tracer_provider` | Optional | Optional   | --                                                       |
| `exit_on_error`              | Optional | Optional   | --                                                       |

### Side-by-Side Comparison

<CodeGroup>
  ```python Version 7 theme={null}
  from arize.experimental.datasets import ArizeDatasetsClient

  # Client initialization
  client = ArizeDatasetsClient(api_key="your-developer-key")

  # Run experiment
  experiment_id, results_df = client.run_experiment(
      space_id="your-space-id",
      experiment_name="my-experiment",
      task=my_task,
      dataset_id="dataset-123",  # or dataset_name="my-dataset"
      evaluators=my_evaluators,
      dry_run=False,
      concurrency=3,
      set_global_tracer_provider=False,
      exit_on_error=False
  )
  ```

  ```python Version 8 theme={null}
  from arize import ArizeClient

  # Client initialization
  client = ArizeClient(api_key="your-api-key")

  # Run experiment
  experiment, results_df = client.experiments.run(
      name="my-experiment",  # Renamed from experiment_name
      dataset_id="dataset-123",  # Required, no dataset_name option
      task=my_task,
      evaluators=my_evaluators,
      dry_run=False,
      dry_run_count=10,  # New parameter
      concurrency=3,
      set_global_tracer_provider=False,
      exit_on_error=False
      # space_id removed
      # dataset_df removed (downloaded automatically)
  )
  experiment_id = experiment.id if experiment else None
  ```
</CodeGroup>

## log\_experiment()

The `log_experiment()` method migrates from `client.log_experiment()` to `client.experiments.create()`.

### Parameter Reference

| Parameter           | v7       | v8         | Changes                                                          |
| ------------------- | -------- | ---------- | ---------------------------------------------------------------- |
| `space_id`          | Required | ❌ Removed  | Not needed in v8                                                 |
| `experiment_name`   | Required | Required   | Renamed to `name`                                                |
| `name`              | N/A      | ✅ Required | Renamed from `experiment_name`                                   |
| `experiment_df`     | Required | Required   | Renamed to `experiment_runs`                                     |
| `experiment_runs`   | N/A      | ✅ Required | Renamed from `experiment_df`; accepts DataFrame or list of dicts |
| `task_columns`      | Required | Required   | Renamed to `task_fields`                                         |
| `task_fields`       | N/A      | ✅ Required | Renamed from `task_columns`                                      |
| `evaluator_columns` | Optional | Optional   | --                                                               |
| `dataset_id`        | Optional | Required   | Now required; no longer accepts `dataset_name`                   |
| `dataset_name`      | Optional | ❌ Removed  | Use `dataset_id` instead                                         |
| `force_http`        | N/A      | ✅ Optional | Force HTTP upload instead of gRPC (default False)                |

### Side-by-Side Comparison

<CodeGroup>
  ```python Version 7 theme={null}
  from arize.experimental.datasets import ArizeDatasetsClient
  from arize.experimental.datasets.experiments.types import (
      ExperimentTaskResultColumnNames,
      EvaluationResultColumnNames
  )

  # Client initialization
  client = ArizeDatasetsClient(api_key="your-developer-key")

  # Log experiment
  experiment_id = client.log_experiment(
      space_id="your-space-id",
      experiment_name="my-experiment",
      experiment_df=results_df,
      task_columns=ExperimentTaskResultColumnNames(
          example_id="example_id",
          result="output"
      ),
      evaluator_columns={
          "accuracy": EvaluationResultColumnNames(
              score="accuracy_score"
          )
      },
      dataset_id="dataset-123"  # or dataset_name="my-dataset"
  )
  ```

  ```python Version 8 theme={null}
  from arize import ArizeClient
  from arize.experiments import ExperimentTaskFieldNames, EvaluationResultFieldNames

  # Client initialization
  client = ArizeClient(api_key="your-api-key")

  # Create experiment
  experiment = client.experiments.create(
      name="my-experiment",  # Renamed from experiment_name
      dataset_id="dataset-123",  # Required, no dataset_name option
      experiment_runs=results_df,  # Renamed from experiment_df
      task_fields=ExperimentTaskFieldNames(  # Renamed from task_columns
          example_id="example_id",
          output="output"
      ),
      evaluator_columns={
          "accuracy": EvaluationResultFieldNames(
              score="accuracy_score"
          )
      },
      force_http=False  # New parameter
      # space_id removed
  )
  experiment_id = experiment.id
  ```
</CodeGroup>

## get\_experiment()

The `get_experiment()` method has a different behavior in v8. In v7, `client.get_experiment()` returned the experiment data including all runs. In v8, `client.experiments.get()` returns only the experiment metadata, while `client.experiments.list_runs()` retrieves the actual experiment runs.

### Parameter Reference

**For experiment metadata (v8's `experiments.get()`):**

| Parameter         | v7       | v8        | Changes                     |
| ----------------- | -------- | --------- | --------------------------- |
| `space_id`        | Required | ❌ Removed | Not needed in v8            |
| `experiment_id`   | Optional | Required  | Now required and simplified |
| `experiment_name` | Optional | ❌ Removed | Use `experiment_id` instead |
| `dataset_name`    | Optional | ❌ Removed | Use `experiment_id` instead |

**For experiment runs (v8's `experiments.list_runs()`):**

| Parameter       | v7       | v8         | Changes                                                                                                             |
| --------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
| `experiment_id` | Optional | Required   | --                                                                                                                  |
| `limit`         | N/A      | ✅ Optional | Maximum number of runs per page (default 100); ignored if `all=True`                                                |
| `all`           | N/A      | ✅ Optional | When `True`, retrieves all runs via Flight (bypasses pagination). When `False` (default), uses REST with pagination |

### Side-by-Side Comparison

<CodeGroup>
  ```python Version 7 theme={null}
  from arize.experimental.datasets import ArizeDatasetsClient

  # Client initialization
  client = ArizeDatasetsClient(api_key="your-developer-key")

  # Get experiment data (includes runs)
  experiment_df = client.get_experiment(
      space_id="your-space-id",
      experiment_id="exp-123"
  )
  # Returns: pandas DataFrame with experiment runs

  # Or get by name
  experiment_df = client.get_experiment(
      space_id="your-space-id",
      experiment_name="my-experiment",
      dataset_name="my-dataset"
  )
  ```

  ```python Version 8 theme={null}
  from arize import ArizeClient

  # Client initialization
  client = ArizeClient(api_key="your-api-key")

  # Step 1: Get experiment metadata
  experiment = client.experiments.get(experiment_id="exp-123")
  # Returns: Experiment object with metadata
  # Does NOT include runs (experiment data)

  # Step 2: Get experiment runs (actual data)
  # Option A: Get all runs at once (uses Flight, more efficient for large experiments)
  runs_response = client.experiments.list_runs(
      experiment_id="exp-123",
      all=True  # Retrieves all runs via Flight (bypasses pagination)
  )
  runs = runs_response.to_df()

  # Option B: Use pagination (uses REST, better for browsing/previewing)
  runs_response = client.experiments.list_runs(
      experiment_id="exp-123",
      limit=100,  # Get 100 runs per page
      all=False  # Use REST with pagination (default)
  )
  runs = runs_response.to_df()
  # Use response.pagination.cursor for next page if needed
  ```
</CodeGroup>

## delete\_experiment()

The `delete_experiment()` method migrates from `client.delete_experiment()` to `client.experiments.delete()`.

### Parameter Reference

| Parameter         | v7       | v8        | Changes                                                            |
| ----------------- | -------- | --------- | ------------------------------------------------------------------ |
| `space_id`        | Required | ❌ Removed | Not needed in v8                                                   |
| `experiment_id`   | Optional | Required  | Now required; no longer accepts `experiment_name` + `dataset_name` |
| `experiment_name` | Optional | ❌ Removed | Use `experiment_id` instead                                        |
| `dataset_name`    | Optional | ❌ Removed | Use `experiment_id` instead                                        |

### Side-by-Side Comparison

<CodeGroup>
  ```python Version 7 theme={null}
  from arize.experimental.datasets import ArizeDatasetsClient

  # Client initialization
  client = ArizeDatasetsClient(api_key="your-developer-key")

  # Delete experiment by ID
  success, deleted_id = client.delete_experiment(
      space_id="your-space-id",
      experiment_id="exp-123"
  )

  # Or delete by name
  success, deleted_id = client.delete_experiment(
      space_id="your-space-id",
      experiment_name="my-experiment",
      dataset_name="my-dataset"
  )
  ```

  ```python Version 8 theme={null}
  from arize import ArizeClient

  # Client initialization
  client = ArizeClient(api_key="your-api-key")

  # Delete experiment by ID
  client.experiments.delete(experiment_id="exp-123")
  # Returns None on success
  ```
</CodeGroup>