Experiments Client

The Experiments client provides methods for managing experiments in the Opik platform.

class opik.rest_api.experiments.client.ExperimentsClient(*, client_wrapper: SyncClientWrapper)

Bases: object

find_experiments(*, page: int | None = None, size: int | None = None, dataset_id: str | None = None, optimization_id: str | None = None, types: str | None = None, name: str | None = None, dataset_deleted: bool | None = None, prompt_id: str | None = None, sorting: str | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → ExperimentPagePublic

Find experiments

Parameters:

  • page (Optional[int])

  • size (Optional[int])

  • dataset_id (Optional[str])

  • optimization_id (Optional[str])

  • types (Optional[str])

  • name (Optional[str])

  • dataset_deleted (Optional[bool])

  • prompt_id (Optional[str])

  • sorting (Optional[str])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Experiments resource

Return type:

ExperimentPagePublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.find_experiments()

create_experiment(*, dataset_name: str, id: str | None = OMIT, name: str | None = OMIT, metadata: Dict[str, Any | None] | None = OMIT, type: Literal['regular', 'trial', 'mini-batch'] | Any | None = OMIT, optimization_id: str | None = OMIT, prompt_version: PromptVersionLinkWrite | None = OMIT, prompt_versions: Sequence[PromptVersionLinkWrite] | None = OMIT, request_options: RequestOptions | None = None) → None

Create experiment

Parameters:

  • dataset_name (str)

  • id (Optional[str])

  • name (Optional[str])

  • metadata (Optional[JsonNodeWrite])

  • type (Optional[ExperimentWriteType])

  • optimization_id (Optional[str])

  • prompt_version (Optional[PromptVersionLinkWrite])

  • prompt_versions (Optional[Sequence[PromptVersionLinkWrite]])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.create_experiment(dataset_name=’dataset_name’, )

create_experiment_items(*, experiment_items: Sequence[ExperimentItem], request_options: RequestOptions | None = None) → None

Create experiment items

Parameters:

  • experiment_items (Sequence[ExperimentItem])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Examples

from Opik import OpikApi from Opik import ExperimentItem client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.create_experiment_items(experiment_items=[ExperimentItem(experiment_id=’experiment_id’, dataset_item_id=’dataset_item_id’, trace_id=’trace_id’, )], )

delete_experiment_items(*, ids: Sequence[str], request_options: RequestOptions | None = None) → None

Delete experiment items

Parameters:

  • ids (Sequence[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.delete_experiment_items(ids=[‘ids’], )

delete_experiments_by_id(*, ids: Sequence[str], request_options: RequestOptions | None = None) → None

Delete experiments by id

Parameters:

  • ids (Sequence[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.delete_experiments_by_id(ids=[‘ids’], )

experiment_items_bulk(*, experiment_name: str, dataset_name: str, items: Sequence[ExperimentItemBulkRecordExperimentItemBulkWriteView], request_options: RequestOptions | None = None) → None

Record experiment items in bulk with traces, spans, and feedback scores. Maximum request size is 4MB.

Parameters:
Return type:

None

Examples

from Opik import OpikApi from Opik import ExperimentItemBulkRecordExperimentItemBulkWriteView client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.experiment_items_bulk(experiment_name=’experiment_name’, dataset_name=’dataset_name’, items=[ExperimentItemBulkRecordExperimentItemBulkWriteView(dataset_item_id=’dataset_item_id’, )], )

find_feedback_score_names(*, experiment_ids: str | None = None, request_options: RequestOptions | None = None) → List[str]

Find Feedback Score names

Parameters:

  • experiment_ids (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Feedback Scores resource

Return type:

List[str]

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.find_feedback_score_names()

get_experiment_by_id(id: str, *, request_options: RequestOptions | None = None) → ExperimentPublic

Get experiment by id

Parameters:

  • id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Experiment resource

Return type:

ExperimentPublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.get_experiment_by_id(id=’id’, )

get_experiment_item_by_id(id: str, *, request_options: RequestOptions | None = None) → ExperimentItemPublic

Get experiment item by id

Parameters:

  • id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Experiment item resource

Return type:

ExperimentItemPublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.experiments.get_experiment_item_by_id(id=’id’, )

stream_experiment_items(*, experiment_name: str, limit: int | None = OMIT, last_retrieved_id: str | None = OMIT, truncate: bool | None = OMIT, request_options: RequestOptions | None = None) → Iterator[bytes]

Stream experiment items

Parameters:

  • experiment_name (str)

  • limit (Optional[int])

  • last_retrieved_id (Optional[str])

  • truncate (Optional[bool]) – Truncate image included in either input, output or metadata

  • request_options (Optional[RequestOptions]) – Request-specific configuration. You can pass in configuration such as chunk_size, and more to customize the request and response.

Returns:

Experiment items stream or error during process

Return type:

Iterator[bytes]

stream_experiments(*, name: str, limit: int | None = OMIT, last_retrieved_id: str | None = OMIT, request_options: RequestOptions | None = None) → Iterator[bytes]

Stream experiments

Parameters:

  • name (str)

  • limit (Optional[int])

  • last_retrieved_id (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration. You can pass in configuration such as chunk_size, and more to customize the request and response.

Returns:

Experiments stream or error during process

Return type:

Iterator[bytes]

Usage Example

import opik

client = opik.Opik()

# Find experiments
experiments = client.rest_client.experiments.find_experiments(
    page=0,
    size=10
)

# Get an experiment by ID
experiment = client.rest_client.experiments.get_experiment_by_id("experiment-id")

# Create a new experiment
client.rest_client.experiments.create_experiment(
    name="my-experiment",
    dataset_name="my-dataset"
)

# Stream experiment items
items_generator = client.rest_client.experiments.stream_experiment_items(
    experiment_id="experiment-id"
)