API Client Classes

This section documents all API client classes for interacting with the HoneyHive platform.

Note

For tracing and observability, use HoneyHiveTracer API Reference (HoneyHiveTracer). This page documents the HoneyHive API client for managing platform resources (datasets, projects, etc.) - typically used in scripts and automation.

HoneyHive Client 

The main client class for interacting with the HoneyHive API.

class honeyhive.api.client.HoneyHive(api_key=None, *, base_url=None, cp_base_url=None, server_url=None, timeout=None, retry_config=None, rate_limit_calls=None, rate_limit_window=None, max_connections=None, max_keepalive=None, test_mode=None, verbose=None, tracer_instance=None)[source]

Bases: object

Main HoneyHive API client.

Provides an ergonomic interface to the HoneyHive API with both sync and async methods.

Example:

client = HoneyHive(api_key="your-api-key")

# Sync
configs = client.configurations.list(project="my-project")

# Async
configs = await client.configurations.list_async(project="my-project")

Parameters:

api_key (str | None)
base_url (str | None)
cp_base_url (str | None)
server_url (str | None)
timeout (float | None)
retry_config (Any | None)
rate_limit_calls (int | None)
rate_limit_window (float | None)
max_connections (int | None)
max_keepalive (int | None)
test_mode (bool | None)
verbose (bool | None)
tracer_instance (Any | None)

configurations: API for managing configurations.

datapoints: API for managing datapoints.

datasets: API for managing datasets.

events: API for managing events.

experiments: API for managing experiment runs.

metrics: API for managing metrics.

projects: API for managing projects.

sessions: API for managing sessions.

tools: API for managing tools.

__init__(api_key=None, *, base_url=None, cp_base_url=None, server_url=None, timeout=None, retry_config=None, rate_limit_calls=None, rate_limit_window=None, max_connections=None, max_keepalive=None, test_mode=None, verbose=None, tracer_instance=None)[source]

Initialize the HoneyHive client.

Parameters:

api_key (str | None) – HoneyHive API key (typically starts with hh_). Falls back to HH_API_KEY environment variable.
base_url (str | None) – API base URL for Data Plane/ingestion. Falls back to HH_API_URL env var, then https://api.honeyhive.ai.
cp_base_url (str | None) – Control Plane API URL for query endpoints. Falls back to HH_CP_API_URL, then HH_API_URL env var.
server_url (str | None) – Deprecated alias for base_url (for backwards compatibility).
timeout (float | None) – Request timeout in seconds (accepted for backwards compat, not used).
retry_config (Any | None) – Retry configuration (accepted for backwards compat, not used).
rate_limit_calls (int | None) – Max calls per time window (accepted for backwards compat).
rate_limit_window (float | None) – Time window in seconds (accepted for backwards compat).
max_connections (int | None) – Max connections in pool (accepted for backwards compat).
max_keepalive (int | None) – Max keepalive connections (accepted for backwards compat).
test_mode (bool | None) – Enable test mode (accepted for backwards compat, not used).
verbose (bool | None) – Enable verbose logging (accepted for backwards compat, not used).
tracer_instance (Any | None) – Tracer instance (accepted for backwards compat, not used).

Return type:

None

property test_mode: bool: Return whether client is in test mode.

property verbose: bool: Return whether verbose mode is enabled.

property timeout: float | None: Return the configured timeout.

property api_config: APIConfig: Access the underlying API configuration.

property api_key: str: Get the HoneyHive API key.

property server_url: str: Get the HoneyHive API server URL.

Usage Example 

from honeyhive import HoneyHive

# Initialize the client
client = HoneyHive(api_key="your-api-key")

# Access API endpoints
datasets = client.datasets.list()
projects = client.projects.list()

DatasetsAPI 

API client for dataset operations.

class honeyhive.api.client.DatasetsAPI(api_config)[source]

Bases: BaseAPI

Datasets API.

Parameters:: api_config (APIConfig)

list(dataset_id=None, name=None, include_datapoints=None)[source]

List datasets.

Parameters:

dataset_id (str | None) – Optional dataset ID to fetch.
name (str | None) – Optional dataset name to filter by.
include_datapoints (bool | None) – Whether to include datapoints in the response.

Return type:

GetDatasetsResponse

create(request)[source]

Create a dataset.

Parameters:: request (CreateDatasetRequest)
Return type:: CreateDatasetResponse

update(request)[source]

Update a dataset.

Parameters:: request (UpdateDatasetRequest)
Return type:: UpdateDatasetResponse

delete(id)[source]

Delete a dataset.

Parameters:: id (str)
Return type:: DeleteDatasetResponse

add_datapoints(dataset_id, request)[source]

Add datapoints to a dataset.

Parameters:

dataset_id (str) – The unique identifier of the dataset to add datapoints to.
request (AddDatapointsToDatasetRequest) – The request containing data and mapping for the datapoints.

Returns:

AddDatapointsResponse with inserted status and datapoint IDs.

Return type:

AddDatapointsResponse

remove_datapoint(dataset_id, datapoint_id)[source]

Remove a datapoint from a dataset.

Parameters:

dataset_id (str) – The unique identifier of the dataset.
datapoint_id (str) – The unique identifier of the datapoint to remove.

Returns:

RemoveDatapointResponse with dereferenced status and message.

Return type:

RemoveDatapointResponse

async list_async(dataset_id=None, name=None, include_datapoints=None)[source]

List datasets asynchronously.

Parameters:

dataset_id (str | None) – Optional dataset ID to fetch.
name (str | None) – Optional dataset name to filter by.
include_datapoints (bool | None) – Whether to include datapoints in the response.

Return type:

GetDatasetsResponse

async create_async(request)[source]

Create a dataset asynchronously.

Parameters:: request (CreateDatasetRequest)
Return type:: CreateDatasetResponse

async update_async(request)[source]

Update a dataset asynchronously.

Parameters:: request (UpdateDatasetRequest)
Return type:: UpdateDatasetResponse

async delete_async(id)[source]

Delete a dataset asynchronously.

Parameters:: id (str)
Return type:: DeleteDatasetResponse

async add_datapoints_async(dataset_id, request)[source]

Add datapoints to a dataset asynchronously.

Parameters:

dataset_id (str) – The unique identifier of the dataset to add datapoints to.
request (AddDatapointsToDatasetRequest) – The request containing data and mapping for the datapoints.

Returns:

AddDatapointsResponse with inserted status and datapoint IDs.

Return type:

AddDatapointsResponse

async remove_datapoint_async(dataset_id, datapoint_id)[source]

Remove a datapoint from a dataset asynchronously.

Parameters:

dataset_id (str) – The unique identifier of the dataset.
datapoint_id (str) – The unique identifier of the datapoint to remove.

Returns:

RemoveDatapointResponse with dereferenced status and message.

Return type:

RemoveDatapointResponse

get_dataset(id)[source]

Get a dataset by ID (backwards compatible alias).

Note: Uses list() with dataset_id filter since there’s no single-get endpoint.

Parameters:: id (str)
Return type:: GetDatasetsResponse

create_dataset(request)[source]

Create a dataset (backwards compatible alias for create()).

Parameters:: request (CreateDatasetRequest)
Return type:: CreateDatasetResponse

update_dataset(request)[source]

Update a dataset (backwards compatible alias for update()).

Parameters:: request (UpdateDatasetRequest)
Return type:: UpdateDatasetResponse

delete_dataset(id)[source]

Delete a dataset (backwards compatible alias for delete()).

Parameters:: id (str)
Return type:: DeleteDatasetResponse

list_datasets(dataset_id=None, name=None, include_datapoints=None)[source]

List datasets (backwards compatible alias).

Parameters:

dataset_id (str | None)
name (str | None)
include_datapoints (bool | None)

Return type:

GetDatasetsResponse

Example 

from honeyhive import HoneyHive
from honeyhive.models import CreateDatasetRequest

client = HoneyHive(api_key="your-api-key")

# Create a dataset
dataset = client.datasets.create(
    CreateDatasetRequest(
        project="your-project",
        name="test-dataset",
        description="Test dataset for evaluation"
    )
)

# List datasets
datasets = client.datasets.list()

# Delete a dataset
client.datasets.delete(id="dataset-id")

DatapointsAPI 

API client for datapoint operations. Datapoints are individual records within datasets.

class honeyhive.api.client.DatapointsAPI(api_config)[source]

Bases: BaseAPI

Datapoints API.

Parameters:: api_config (APIConfig)

list(datapoint_ids=None, dataset_name=None)[source]

List datapoints.

Parameters:

datapoint_ids (List[str] | None) – Optional list of datapoint IDs to fetch.
dataset_name (str | None) – Optional dataset name to filter by.

Return type:

GetDatapointsResponse

get(id)[source]

Get a datapoint by ID.

Parameters:: id (str)
Return type:: GetDatapointResponse

create(request)[source]

Create a datapoint.

Parameters:: request (CreateDatapointRequest)
Return type:: CreateDatapointResponse

update(id, request)[source]

Update a datapoint.

Parameters:

id (str)
request (UpdateDatapointRequest)

Return type:

UpdateDatapointResponse

delete(id)[source]

Delete a datapoint.

Parameters:: id (str)
Return type:: DeleteDatapointResponse

async list_async(datapoint_ids=None, dataset_name=None)[source]

List datapoints asynchronously.

Parameters:

datapoint_ids (List[str] | None) – Optional list of datapoint IDs to fetch.
dataset_name (str | None) – Optional dataset name to filter by.

Return type:

GetDatapointsResponse

async get_async(id)[source]

Get a datapoint by ID asynchronously.

Parameters:: id (str)
Return type:: GetDatapointResponse

async create_async(request)[source]

Create a datapoint asynchronously.

Parameters:: request (CreateDatapointRequest)
Return type:: CreateDatapointResponse

async update_async(id, request)[source]

Update a datapoint asynchronously.

Parameters:

id (str)
request (UpdateDatapointRequest)

Return type:

UpdateDatapointResponse

async delete_async(id)[source]

Delete a datapoint asynchronously.

Parameters:: id (str)
Return type:: DeleteDatapointResponse

get_datapoint(id)[source]

Get a datapoint by ID (backwards compatible alias for get()).

Parameters:: id (str)
Return type:: GetDatapointResponse

create_datapoint(request)[source]

Create a datapoint (backwards compatible alias for create()).

Parameters:: request (CreateDatapointRequest)
Return type:: CreateDatapointResponse

update_datapoint(id, request)[source]

Update a datapoint (backwards compatible alias for update()).

Parameters:

id (str)
request (UpdateDatapointRequest)

Return type:

UpdateDatapointResponse

delete_datapoint(id)[source]

Delete a datapoint (backwards compatible alias for delete()).

Parameters:: id (str)
Return type:: DeleteDatapointResponse

list_datapoints(datapoint_ids=None, dataset_name=None)[source]

List datapoints (backwards compatible alias).

Parameters:

datapoint_ids (List[str] | None)
dataset_name (str | None)

Return type:

GetDatapointsResponse

Example 

from honeyhive import HoneyHive
from honeyhive.models import CreateDatapointRequest

client = HoneyHive(api_key="your-api-key")

# Create a datapoint
datapoint = client.datapoints.create(
    CreateDatapointRequest(
        inputs={"query": "What is machine learning?"},
        ground_truth="Machine learning is a subset of AI...",
        linked_datasets=["dataset-id"]
    )
)

# List datapoints for a dataset
datapoints = client.datapoints.list(dataset_id="dataset-id")

# Get specific datapoint
datapoint = client.datapoints.get(id="datapoint-id")

ConfigurationsAPI 

API client for configuration operations.

class honeyhive.api.client.ConfigurationsAPI(api_config)[source]

Bases: BaseAPI

Configurations API.

Parameters:: api_config (APIConfig)

list(project=None)[source]

List configurations.

Note: project parameter is currently unused as v1 API doesn’t support project filtering.

Parameters:: project (str | None)
Return type:: List[GetConfigurationsResponse]

create(request)[source]

Create a configuration.

Parameters:: request (CreateConfigurationRequest)
Return type:: CreateConfigurationResponse

update(id, request)[source]

Update a configuration.

Parameters:

id (str)
request (UpdateConfigurationRequest)

Return type:

UpdateConfigurationResponse

delete(id)[source]

Delete a configuration.

Parameters:: id (str)
Return type:: DeleteConfigurationResponse

async list_async(project=None)[source]

List configurations asynchronously.

Note: project parameter is currently unused as v1 API doesn’t support project filtering.

Parameters:: project (str | None)
Return type:: List[GetConfigurationsResponse]

async create_async(request)[source]

Create a configuration asynchronously.

Parameters:: request (CreateConfigurationRequest)
Return type:: CreateConfigurationResponse

async update_async(id, request)[source]

Update a configuration asynchronously.

Parameters:

id (str)
request (UpdateConfigurationRequest)

Return type:

UpdateConfigurationResponse

async delete_async(id)[source]

Delete a configuration asynchronously.

Parameters:: id (str)
Return type:: DeleteConfigurationResponse

get_configuration(id)[source]

Get a configuration (backwards compatible alias).

Parameters:: id (str)
Return type:: GetConfigurationsResponse

create_configuration(request)[source]

Create a configuration (backwards compatible alias).

Parameters:: request (CreateConfigurationRequest)
Return type:: CreateConfigurationResponse

update_configuration(id, request)[source]

Update a configuration (backwards compatible alias).

Parameters:

id (str)
request (UpdateConfigurationRequest)

Return type:

UpdateConfigurationResponse

delete_configuration(id)[source]

Delete a configuration (backwards compatible alias).

Parameters:: id (str)
Return type:: DeleteConfigurationResponse

list_configurations(project=None)[source]

List configurations (backwards compatible alias).

Parameters:: project (str | None)
Return type:: List[GetConfigurationsResponse]

MetricsAPI 

API client for metrics operations.

class honeyhive.api.client.MetricsAPI(api_config)[source]

Bases: BaseAPI

Metrics API.

Parameters:: api_config (APIConfig)

list(project=None, name=None, type=None)[source]

List metrics.

Parameters:

project (str | None)
name (str | None)
type (str | None)

Return type:

GetMetricsResponse

create(request)[source]

Create a metric.

Parameters:: request (CreateMetricRequest)
Return type:: CreateMetricResponse

update(request)[source]

Update a metric.

Parameters:: request (UpdateMetricRequest)
Return type:: UpdateMetricResponse

delete(id)[source]

Delete a metric.

Parameters:: id (str)
Return type:: DeleteMetricResponse

async list_async(project=None, name=None, type=None)[source]

List metrics asynchronously.

Parameters:

project (str | None)
name (str | None)
type (str | None)

Return type:

GetMetricsResponse

async create_async(request)[source]

Create a metric asynchronously.

Parameters:: request (CreateMetricRequest)
Return type:: CreateMetricResponse

async update_async(request)[source]

Update a metric asynchronously.

Parameters:: request (UpdateMetricRequest)
Return type:: UpdateMetricResponse

async delete_async(id)[source]

Delete a metric asynchronously.

Parameters:: id (str)
Return type:: DeleteMetricResponse

get_metric(id)[source]

Get a metric (backwards compatible alias).

Parameters:: id (str)
Return type:: GetMetricsResponse

create_metric(request)[source]

Create a metric (backwards compatible alias).

Parameters:: request (CreateMetricRequest)
Return type:: CreateMetricResponse

update_metric(request)[source]

Update a metric (backwards compatible alias).

Parameters:: request (UpdateMetricRequest)
Return type:: UpdateMetricResponse

delete_metric(id)[source]

Delete a metric (backwards compatible alias).

Parameters:: id (str)
Return type:: DeleteMetricResponse

list_metrics(project=None, name=None, type=None)[source]

List metrics (backwards compatible alias).

Parameters:

project (str | None)
name (str | None)
type (str | None)

Return type:

GetMetricsResponse

Example 

from honeyhive import HoneyHive

client = HoneyHive(api_key="your-api-key")

# List metrics
metrics = client.metrics.list()

# Run a metric
result = client.metrics.run(metric_id="metric-id", event_id="event-id")

ProjectsAPI 

API client for project operations.

class honeyhive.api.client.ProjectsAPI(api_config)[source]

Bases: BaseAPI

Projects API.

Parameters:: api_config (APIConfig)

list(name=None)[source]

List projects.

Parameters:: name (str | None)
Return type:: Dict[str, Any]

create(data)[source]

Create a project.

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

update(data)[source]

Update a project.

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

delete(name)[source]

Delete a project.

Parameters:: name (str)
Return type:: Dict[str, Any]

async list_async(name=None)[source]

List projects asynchronously.

Parameters:: name (str | None)
Return type:: Dict[str, Any]

async create_async(data)[source]

Create a project asynchronously.

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

async update_async(data)[source]

Update a project asynchronously.

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

async delete_async(name)[source]

Delete a project asynchronously.

Parameters:: name (str)
Return type:: Dict[str, Any]

get_project(id)[source]

Get a project (backwards compatible alias).

Parameters:: id (str)
Return type:: Dict[str, Any]

create_project(data)[source]

Create a project (backwards compatible alias).

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

update_project(data)[source]

Update a project (backwards compatible alias).

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

delete_project(name)[source]

Delete a project (backwards compatible alias).

Parameters:: name (str)
Return type:: Dict[str, Any]

list_projects(name=None)[source]

List projects (backwards compatible alias).

Parameters:: name (str | None)
Return type:: Dict[str, Any]

Example 

from honeyhive import HoneyHive
from honeyhive.models import PostProjectRequest

client = HoneyHive(api_key="your-api-key")

# Create a project
project = client.projects.create(
    PostProjectRequest(
        name="my-llm-project",
        type="evaluation"
    )
)

# List all projects
projects = client.projects.list()

SessionsAPI 

API client for session operations.

class honeyhive.api.client.SessionsAPI(api_config)[source]

Bases: BaseAPI

Sessions API.

Parameters:: api_config (APIConfig)

get(session_id)[source]

Get a session by ID.

Parameters:: session_id (str)
Return type:: GetSessionResponse

delete(session_id)[source]

Delete a session.

Parameters:: session_id (str)
Return type:: DeleteSessionResponse

start(data)[source]

Start a new session.

Parameters:: data (Dict[str, Any])
Return type:: PostSessionStartResponse

async get_async(session_id)[source]

Get a session by ID asynchronously.

Parameters:: session_id (str)
Return type:: GetSessionResponse

async delete_async(session_id)[source]

Delete a session asynchronously.

Parameters:: session_id (str)
Return type:: DeleteSessionResponse

async start_async(data)[source]

Start a new session asynchronously.

Parameters:: data (Dict[str, Any])
Return type:: PostSessionStartResponse

create_session(request)[source]

Create/start a session (backwards compatible alias for start()).

Parameters:: request (Dict[str, Any])
Return type:: PostSessionStartResponse

start_session(request)[source]

Start a session (backwards compatible alias for start()).

Parameters:: request (Dict[str, Any])
Return type:: PostSessionStartResponse

get_session(session_id)[source]

Get a session (backwards compatible alias for get()).

Parameters:: session_id (str)
Return type:: GetSessionResponse

delete_session(session_id)[source]

Delete a session (backwards compatible alias for delete()).

Parameters:: session_id (str)
Return type:: DeleteSessionResponse

Example 

from honeyhive import HoneyHive
from honeyhive.models import PostSessionRequest

client = HoneyHive(api_key="your-api-key")

# Start a session
session = client.sessions.start(
    PostSessionRequest(
        project="your-project",
        session_name="user-interaction"
    )
)

print(f"Session ID: {session.session_id}")

ToolsAPI 

API client for tool operations.

class honeyhive.api.client.ToolsAPI(api_config)[source]

Bases: BaseAPI

Tools API.

Parameters:: api_config (APIConfig)

list()[source]

List tools.

Return type:: List[GetToolsResponse]

create(request)[source]

Create a tool.

Parameters:: request (CreateToolRequest)
Return type:: CreateToolResponse

update(request)[source]

Update a tool.

Parameters:: request (UpdateToolRequest)
Return type:: UpdateToolResponse

delete(id)[source]

Delete a tool.

Parameters:: id (str)
Return type:: DeleteToolResponse

async list_async()[source]

List tools asynchronously.

Return type:: List[GetToolsResponse]

async create_async(request)[source]

Create a tool asynchronously.

Parameters:: request (CreateToolRequest)
Return type:: CreateToolResponse

async update_async(request)[source]

Update a tool asynchronously.

Parameters:: request (UpdateToolRequest)
Return type:: UpdateToolResponse

async delete_async(id)[source]

Delete a tool asynchronously.

Parameters:: id (str)
Return type:: DeleteToolResponse

get_tool(id)[source]

Get a tool (backwards compatible alias).

Parameters:: id (str)
Return type:: List[GetToolsResponse]

create_tool(request)[source]

Create a tool (backwards compatible alias).

Parameters:: request (CreateToolRequest)
Return type:: CreateToolResponse

update_tool(request)[source]

Update a tool (backwards compatible alias).

Parameters:: request (UpdateToolRequest)
Return type:: UpdateToolResponse

delete_tool(id)[source]

Delete a tool (backwards compatible alias).

Parameters:: id (str)
Return type:: DeleteToolResponse

list_tools()[source]

List tools (backwards compatible alias).

Return type:: List[GetToolsResponse]

Example 

from honeyhive import HoneyHive
from honeyhive.models import CreateToolRequest

client = HoneyHive(api_key="your-api-key")

# Create a tool
tool = client.tools.create(
    CreateToolRequest(
        name="calculator",
        description="Performs mathematical calculations",
        parameters={
            "type": "object",
            "properties": {
                "operation": {"type": "string"},
                "a": {"type": "number"},
                "b": {"type": "number"}
            }
        }
    )
)

# List all tools
tools = client.tools.list()

ExperimentsAPI 

API client for experiment/evaluation operations.

class honeyhive.api.client.ExperimentsAPI(api_config)[source]

Bases: BaseAPI

Experiments API.

Parameters:: api_config (APIConfig)

get_schema(dateRange=None, evaluation_id=None)[source]

Get experiment runs schema.

Parameters:

dateRange (Any | None) – Filter by date range (string or dict with $gte/$lte).
evaluation_id (str | None) – Filter by evaluation/run ID.

Return type:

GetExperimentRunsSchemaResponse

list_runs(dataset_id=None, page=None, limit=None, run_ids=None, name=None, status=None, dateRange=None, sort_by=None, sort_order=None)[source]

List experiment runs.

Parameters:

dataset_id (str | None) – Filter by dataset ID.
page (int | None) – Page number for pagination.
limit (int | None) – Number of results per page.
run_ids (List[str] | None) – Filter by specific run IDs.
name (str | None) – Filter by run name.
status (str | None) – Filter by run status.
dateRange (Any | None) – Filter by date range.
sort_by (str | None) – Sort by field.
sort_order (str | None) – Sort order (asc/desc).

Return type:

GetExperimentRunsResponse

get_run(run_id)[source]

Get an experiment run by ID.

Parameters:: run_id (str)
Return type:: GetExperimentRunResponse

create_run(request)[source]

Create an experiment run.

Parameters:: request (PostExperimentRunRequest)
Return type:: PostExperimentRunResponse

update_run(run_id, request)[source]

Update an experiment run.

Parameters:

run_id (str)
request (PutExperimentRunRequest)

Return type:

PutExperimentRunResponse

delete_run(run_id)[source]

Delete an experiment run.

Parameters:: run_id (str)
Return type:: DeleteExperimentRunResponse

async get_schema_async(dateRange=None, evaluation_id=None)[source]

Get experiment runs schema asynchronously.

Parameters:

dateRange (Any | None) – Filter by date range (string or dict with $gte/$lte).
evaluation_id (str | None) – Filter by evaluation/run ID.

Return type:

GetExperimentRunsSchemaResponse

async list_runs_async(dataset_id=None, page=None, limit=None, run_ids=None, name=None, status=None, dateRange=None, sort_by=None, sort_order=None)[source]

List experiment runs asynchronously.

Parameters:

dataset_id (str | None) – Filter by dataset ID.
page (int | None) – Page number for pagination.
limit (int | None) – Number of results per page.
run_ids (List[str] | None) – Filter by specific run IDs.
name (str | None) – Filter by run name.
status (str | None) – Filter by run status.
dateRange (Any | None) – Filter by date range.
sort_by (str | None) – Sort by field.
sort_order (str | None) – Sort order (asc/desc).

Return type:

GetExperimentRunsResponse

async get_run_async(run_id)[source]

Get an experiment run by ID asynchronously.

Parameters:: run_id (str)
Return type:: GetExperimentRunResponse

async create_run_async(request)[source]

Create an experiment run asynchronously.

Parameters:: request (PostExperimentRunRequest)
Return type:: PostExperimentRunResponse

async update_run_async(run_id, request)[source]

Update an experiment run asynchronously.

Parameters:

run_id (str)
request (PutExperimentRunRequest)

Return type:

PutExperimentRunResponse

async delete_run_async(run_id)[source]

Delete an experiment run asynchronously.

Parameters:: run_id (str)
Return type:: DeleteExperimentRunResponse

get_result(run_id, aggregate_function=None, filters=None)[source]

Get experiment run result.

Parameters:

run_id (str) – The experiment run ID.
aggregate_function (str | None) – Aggregation function to apply.
filters (Any | None) – Optional filters to apply.

Return type:

Dict[str, Any]

compare_runs(new_run_id, old_run_id, aggregate_function=None, filters=None)[source]

Compare two experiment runs.

Parameters:

new_run_id (str) – The new run ID to compare.
old_run_id (str) – The old run ID to compare against.
aggregate_function (str | None) – Aggregation function to apply.
filters (Any | None) – Optional filters to apply.

Return type:

Dict[str, Any]

async get_result_async(run_id, aggregate_function=None, filters=None)[source]

Get experiment run result asynchronously.

Parameters:

run_id (str) – The experiment run ID.
aggregate_function (str | None) – Aggregation function to apply.
filters (Any | None) – Optional filters to apply.

Return type:

Dict[str, Any]

async compare_runs_async(new_run_id, old_run_id, aggregate_function=None, filters=None)[source]

Compare two experiment runs asynchronously.

Parameters:

new_run_id (str) – The new run ID to compare.
old_run_id (str) – The old run ID to compare against.
aggregate_function (str | None) – Aggregation function to apply.
filters (Any | None) – Optional filters to apply.

Return type:

Dict[str, Any]

get_run_result(run_id, aggregate_function=None, filters=None)[source]

Get experiment run result (alias for get_result).

Parameters:

run_id (str)
aggregate_function (str | None)
filters (Any | None)

Return type:

Dict[str, Any]

compare_run_events(new_run_id, old_run_id, event_name=None, event_type=None, filter=None, limit=None, page=None)[source]

Compare events between two experiment runs.

Parameters:

new_run_id (str) – The new run ID to compare.
old_run_id (str) – The old run ID to compare against.
event_name (str | None) – Filter by event name.
event_type (str | None) – Filter by event type.
filter (Any | None) – Additional filter criteria.
limit (int | None) – Maximum number of results.
page (int | None) – Page number for pagination.

Return type:

Dict[str, Any]

Example 

from honeyhive import HoneyHive

client = HoneyHive(api_key="your-api-key")

# List experiment runs
runs = client.experiments.list_runs()

# Get experiment result
result = client.experiments.get_result(run_id="run-id")

EventsAPI 

API client for event operations.

class honeyhive.api.client.EventsAPI(api_config)[source]

Bases: BaseAPI

Events API.

Read operations (list, get_by_session_id, delete) use Control Plane. Write operations (create, update, create_batch) use Data Plane.

Parameters:: api_config (APIConfig)

list(query)[source]

Get events (uses Control Plane endpoint).

Parameters:: query (GetEventsQuery | Dict[str, Any]) – Query parameters as GetEventsQuery model or dict. Supported fields: dateRange, filters, projections, ignore_order, limit, page, evaluation_id
Returns:: GetEventsResponse with matching events
Return type:: GetEventsResponse

get_by_session_id(session_id, project=None, *, limit=1000)[source]

Get events by session ID using the Data Plane export endpoint.

This is a convenience wrapper around export() that filters by session_id. Events are returned sorted by start_time in chronological order.

Parameters:

session_id (str) – The session ID to fetch events for.
project (str | None) – Project name associated with the events. Deprecated in v1.0 and will be removed in v2.0. The backend now infers project from session_id.
limit (int) – Maximum number of events to return (default 1000).

Returns:

EventExportResponse with events for the session, sorted by start_time.

Return type:

EventExportResponse

Example:

response = client.events.get_by_session_id(
    session_id="abc-123"
)
for event in response.events:
    print(event["event_name"])

create(request)[source]

Create an event.

Parameters:: request (PostEventRequest)
Return type:: PostEventResponse

update(data)[source]

Update an event.

Parameters:: data (Dict[str, Any])
Return type:: None

create_batch(data)[source]

Create events in batch.

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

export(project=None, filters=None, *, date_range=None, projections=None, limit=1000, page=1, _sort_by_time=False)[source]

Export events via POST /events/export (Data Plane).

This is the primary method for retrieving events from HoneyHive. It uses the Data Plane endpoint which supports filtering by session_id, event_type, and other fields.

Parameters:

project (str | None) – Project name associated with the events. Deprecated in v1.0 and will be removed in v2.0. The backend now infers project from filters (e.g., session_id).
filters (List[EventFilter | Dict[str, Any]] | None) – List of EventFilter objects or dicts with filter criteria. Each filter should have: field, operator, value, type.
date_range (Dict[str, str] | None) – Optional date range filter with ‘$gte’ and ‘$lte’ keys containing ISO timestamp strings.
projections (List[str] | None) – Optional list of fields to include in the response.
limit (int) – Maximum number of results (default 1000, max 7500).
page (int) – Page number for pagination (default 1).
_sort_by_time (bool) – Internal flag to sort events by start_time (default False).

Returns:

EventExportResponse with events list and total_events count.

Return type:

EventExportResponse

Example:

from honeyhive.models import EventFilter

# Export events for a session
response = client.events.export(
    filters=[
        EventFilter(
            field="session_id",
            operator="is",
            value="abc-123",
            type="string"
        )
    ],
    limit=100
)

for event in response.events:
    print(event["event_name"])

# Export with date range
response = client.events.export(
    filters=[],
    date_range={
        "$gte": "2024-01-01T00:00:00Z",
        "$lte": "2024-01-31T23:59:59Z"
    }
)

async list_async(query)[source]

Get events asynchronously (uses Control Plane endpoint).

Parameters:: query (GetEventsQuery | Dict[str, Any]) – Query parameters as GetEventsQuery model or dict.
Returns:: GetEventsResponse with matching events
Return type:: GetEventsResponse

async get_by_session_id_async(session_id, project=None, *, limit=1000)[source]

Get events by session ID asynchronously using the Data Plane export endpoint.

Async version of get_by_session_id(). See get_by_session_id() for full documentation. Events are returned sorted by start_time in chronological order.

Parameters:

session_id (str) – The session ID to fetch events for.
project (str | None) – Project name associated with the events. Deprecated in v1.0 and will be removed in v2.0. The backend now infers project from session_id.
limit (int) – Maximum number of events to return (default 1000).

Returns:

EventExportResponse with events for the session, sorted by start_time.

Return type:

EventExportResponse

async create_async(request)[source]

Create an event asynchronously.

Parameters:: request (PostEventRequest)
Return type:: PostEventResponse

async update_async(data)[source]

Update an event asynchronously.

Parameters:: data (Dict[str, Any])
Return type:: None

async create_batch_async(data)[source]

Create events in batch asynchronously.

Parameters:: data (Dict[str, Any])
Return type:: Dict[str, Any]

async export_async(project=None, filters=None, *, date_range=None, projections=None, limit=1000, page=1, _sort_by_time=False)[source]

Export events via POST /events/export asynchronously (Data Plane).

Async version of export(). See export() for full documentation.

Parameters:

project (str | None) – Project name associated with the events. Deprecated in v1.0 and will be removed in v2.0. The backend now infers project from filters (e.g., session_id).
filters (List[EventFilter | Dict[str, Any]] | None) – List of EventFilter objects or dicts with filter criteria.
date_range (Dict[str, str] | None) – Optional date range filter.
projections (List[str] | None) – Optional list of fields to include in the response.
limit (int) – Maximum number of results (default 1000, max 7500).
page (int) – Page number for pagination (default 1).
_sort_by_time (bool) – Internal flag to sort events by start_time (default False).

Returns:

EventExportResponse with events list and total_events count.

Return type:

EventExportResponse

create_event(request)[source]

Create an event (backwards compatible alias for create()).

Parameters:: request (PostEventRequest)
Return type:: PostEventResponse

update_event(data)[source]

Update an event (backwards compatible alias for update()).

Parameters:: data (Dict[str, Any])
Return type:: None

list_events(project=None, filters=None, *, date_range=None, projections=None, limit=1000, page=1)[source]

List events via export endpoint (backwards compatible alias).

This is a backwards compatible alias for export(). Uses the Data Plane POST /events/export endpoint.

Parameters:

project (str | None) – Project name. Deprecated in v1.0 and will be removed in v2.0.
filters (List[EventFilter | Dict[str, Any]] | None) – List of EventFilter objects or dicts.
date_range (Dict[str, str] | None) – Optional date range filter.
projections (List[str] | None) – Optional list of fields to include.
limit (int) – Maximum number of results (default 1000).
page (int) – Page number (default 1).

Returns:

EventExportResponse with events and total count.

Return type:

EventExportResponse

get_events(project=None, filters=None, *, date_range=None, projections=None, limit=1000, page=1)[source]

Get events via export endpoint (backwards compatible alias).

This is a backwards compatible alias for export(). Uses the Data Plane POST /events/export endpoint.

Parameters:

project (str | None) – Project name. Deprecated in v1.0 and will be removed in v2.0.
filters (List[EventFilter | Dict[str, Any]] | None) – List of EventFilter objects or dicts.
date_range (Dict[str, str] | None) – Optional date range filter.
projections (List[str] | None) – Optional list of fields to include.
limit (int) – Maximum number of results (default 1000).
page (int) – Page number (default 1).

Returns:

EventExportResponse with events and total count.

Return type:

EventExportResponse

async list_events_async(project=None, filters=None, *, date_range=None, projections=None, limit=1000, page=1)[source]

List events asynchronously (backwards compatible alias for export_async).

Parameters:

project (str | None) – Project name. Deprecated in v1.0 and will be removed in v2.0.
filters (List[EventFilter | Dict[str, Any]] | None)
date_range (Dict[str, str] | None)
projections (List[str] | None)
limit (int)
page (int)

Return type:

EventExportResponse

async get_events_async(project=None, filters=None, *, date_range=None, projections=None, limit=1000, page=1)[source]

Get events asynchronously (backwards compatible alias for export_async).

Parameters:

project (str | None) – Project name. Deprecated in v1.0 and will be removed in v2.0.
filters (List[EventFilter | Dict[str, Any]] | None)
date_range (Dict[str, str] | None)
projections (List[str] | None)
limit (int)
page (int)

Return type:

EventExportResponse

Example 

from honeyhive import HoneyHive
from honeyhive.models import PostEventRequest

client = HoneyHive(api_key="your-api-key")

# Post an event
response = client.events.post(
    PostEventRequest(
        project="your-project",
        event_type="model",
        model="gpt-4",
        inputs={"prompt": "Hello"},
        outputs={"response": "Hi there!"}
    )
)