HoneyHive Docs

Constructor

new Client(options: ClientConfig = {}): Client

Namespaces

charts

create

create(request: CreateChartRequest): Promise<CreateChartResponse>

Create a new chart

delete

delete(request: DeleteChartRequest): Promise<DeleteChartResponse>

Delete a chart

get

get(request: GetChartRequest): Promise<GetChartResponse>

Get a chart Retrieve a single chart by id.

list

list(): Promise<GetChartsResponse>

List charts Retrieve all charts in the current scope.

update

update(request: UpdateChartRequest): Promise<UpdateChartResponse>

Update a chart Update a chart’s editable fields. Only fields included in the request body are modified.

datapoints

create

create(request: CreateDatapointRequest): Promise<CreateDatapointResponse>

Create a new datapoint Create a single datapoint with inputs, history, ground truth, and metadata.

createBatch

createBatch(request: BatchCreateDatapointsRequest): Promise<BatchCreateDatapointsResponse>

Create multiple datapoints in batch Create multiple datapoints from events using field mappings and optional filters.

delete

delete(request: DeleteDatapointRequest): Promise<DeleteDatapointResponse>

Delete a specific datapoint Permanently delete a datapoint by its unique identifier.

get

get(request: GetDatapointRequest): Promise<GetDatapointResponse>

Retrieve a specific datapoint Get a single datapoint by its unique identifier.

list

list(request?: GetDatapointsRequest): Promise<GetDatapointsResponse>

Retrieve a list of datapoints Retrieve datapoints, optionally filtered by a list of datapoint IDs or dataset name.

update

update(request: UpdateDatapointRequest): Promise<UpdateDatapointResponse>

Update a specific datapoint Update fields on an existing datapoint. Only the provided fields are modified.

datasets

addDatapoints

addDatapoints(request: AddDatapointsRequest): Promise<AddDatapointsResponse>

Add datapoints to a dataset Add new datapoints to an existing dataset. Provide raw data objects and a field mapping that specifies which fields map to inputs, ground truth, and history.

create

create(request: CreateDatasetRequest): Promise<CreateDatasetResponse>

Create a dataset Create a new dataset with an optional name, description, and initial set of datapoint IDs.

delete

delete(request: DeleteDatasetRequest): Promise<DeleteDatasetResponse>

Delete a dataset Permanently delete a dataset by its unique identifier.

list

list(request?: GetDatasetsRequest): Promise<GetDatasetsResponse>

Get datasets Retrieve datasets, optionally filtered by dataset ID or name.

removeDatapoint

removeDatapoint(request: RemoveDatapointRequest): Promise<RemoveDatapointResponse>

Remove a datapoint from a dataset Remove a specific datapoint from a dataset. The datapoint itself is not deleted, only dereferenced from the dataset.

update

update(request: UpdateDatasetRequest): Promise<UpdateDatasetResponse>

Update a dataset Update a dataset’s name, description, or list of datapoint IDs.

events

create

create(request: CreateEventRequest): Promise<CreateEventResponse>

Create a new event Create a new event (span) within a session trace. The request body is a bare event object (no event wrapper). Required properties:

event_type (string): Must be one of: chain, model, tool, session.
inputs (object): Input data for the event.

Auto-generated properties (provided by the server when omitted):

event_id (string, UUID): Unique identifier for the event.
session_id (string, UUID): Session/trace identifier.
parent_id (string, UUID): Parent event ID. Defaults to session_id.

Optional properties with defaults:

event_name (string): Name of the event. Defaults to "unknown".
source (string): Source of the event (e.g. sdk-python). Defaults to "unknown".

Optional properties:

config (object): Configuration data (e.g. model parameters, prompt templates).
outputs (object): Output data from the event.
error (string or null): Error message if the event failed.
children_ids (array of strings): IDs of child events.
duration (number): Duration of the event in milliseconds.
start_time (number): Unix timestamp in milliseconds for event start.
end_time (number): Unix timestamp in milliseconds for event end.
metadata (object): Additional metadata (e.g. token counts, cost).
metrics (object): Custom metrics.
feedback (object): Feedback data (e.g. ratings, ground truth).
user_properties (object): User properties associated with the event.

Example response

{
  "event_id": "7f22137a-6911-4ed3-bc36-110f1dde6b66",
  "success": true
}

createBatch

createBatch(request: CreateEventBatchRequest): Promise<CreateEventBatchResponse>

Create a batch of events Create multiple events in a single request. When single_session is true, all events share the same session created from session_properties. Required properties:

events (array of event objects): Each event must include event_type (one of chain, model, tool, session) and inputs.

Optional properties:

single_session (boolean): If true, all events share a single session created from session_properties. Defaults to false.
session_properties (object): Session metadata used when single_session is true. May include session_name, start_time, metadata.

Unknown top-level fields and per-event fields are rejected at the SDK boundary; the legacy aliases is_single_session, session, and per-event project are no longer accepted.

Example response

{
  "event_ids": [
    "7f22137a-6911-4ed3-bc36-110f1dde6b66",
    "7f22137a-6911-4ed3-bc36-110f1dde6b67"
  ],
  "session_id": "caf77ace-3417-4da4-944d-f4a0688f3c23",
  "success": true
}

search

search(request: SearchEventsRequest): Promise<SearchEventsResponse>

Retrieve events based on filters Search events via POST with filtering and pagination. This is the primary method for retrieving events from HoneyHive.

update

update(request: UpdateEventRequest): Promise<void>

Update an event Update fields on an existing event. Only the provided fields are modified; omitted fields are left unchanged. Extra fields not listed below are accepted by the server but silently ignored.

Example request

{
  "metadata": {
    "cost": 0.00008,
    "completion_tokens": 23,
    "prompt_tokens": 35,
    "total_tokens": 58
  },
  "feedback": {
    "rating": 5
  },
  "metrics": {
    "num_words": 2
  },
  "outputs": {
    "role": "assistant",
    "content": "Hello world"
  },
  "config": {
    "template": [
      {
        "role": "system",
        "content": "Hello, {{ name }}!"
      }
    ]
  },
  "user_properties": {
    "user_id": "691b1f94-d38c-4e92-b051-5e03fee9ff86"
  },
  "duration": 42
}

experiments

compareRunEvents

compareRunEvents(request: GetExperimentCompareEventsRequest): Promise<GetExperimentCompareEventsResponse>

Compare events between two experiment runs Retrieve and compare events between two experiment runs for detailed analysis

compareRuns

compareRuns(request: GetExperimentComparisonRequest): Promise<GetExperimentComparisonResponse>

Retrieve experiment comparison Compare metrics and results between two experiment runs

createRun

createRun(request: CreateRunRequest): Promise<CreateRunResponse>

Create a new evaluation run Create a new experiment run to track an evaluation against a dataset.

deleteRun

deleteRun(request: DeleteRunRequest): Promise<DeleteRunResponse>

Delete an evaluation run Permanently delete an experiment run by its run ID.

getRun

getRun(request: GetRunRequest): Promise<GetRunResponse>

Get details of an evaluation run Retrieve the full details of a single experiment run by its run ID.

getRunMetrics

getRunMetrics(request: GetExperimentRunMetricsRequest): Promise<GetExperimentRunMetricsResponse>

Get event metrics for an experiment run Retrieve event metrics from ClickHouse for a specific experiment run

getRunSchema

getRunSchema(request: GetRunSchemaRequest): Promise<GetRunSchemaResponse>

Get events schema for a single experiment run Retrieve the events schema (fields, datasets, mappings) for a single experiment run.

getRunsSchema

getRunsSchema(request?: GetRunsSchemaRequest): Promise<GetRunsSchemaResponse>

Get events schema across all experiment runs in a project Retrieve the aggregated events schema (fields, datasets, mappings) across all experiment runs in the project.

getSummary

getSummary(request: GetExperimentSummaryRequest): Promise<GetExperimentSummaryResponse>

Retrieve experiment summary Compute evaluation summary for an experiment run: pass/fail results, metric aggregations, per-datapoint results, event details, and the experiment run object.

listRuns

listRuns(request?: GetRunsRequest): Promise<GetRunsResponse>

Get a list of evaluation runs List experiment runs with optional filtering by dataset, status, name, date range, and specific run IDs. Results are paginated and sortable.

updateRun

updateRun(request: UpdateRunRequest): Promise<UpdateRunResponse>

Update an evaluation run Update fields on an existing experiment run such as name, status, metadata, or results.

metricVersions

create

create(request: CreateMetricVersionRequest): Promise<CreateMetricVersionResponse>

Create a new metric version Snapshot the supplied metric definition as a new version. By default the version is created as a draft (deployed: false); set deploy_immediately: true to also make it the live version in the same transaction.

deploy

deploy(request: DeployMetricVersionRequest): Promise<DeployMetricVersionResponse>

Deploy a specific metric version Mark the named version as the live version for the metric, unmarking any previously deployed version.

list

list(request: GetMetricVersionsRequest): Promise<GetMetricVersionsResponse>

List versions for a metric Retrieve all snapshot versions of the metric’s definition, ordered oldest-first. Returns the full version history unpaginated.

metrics

create

create(request: CreateMetricRequest): Promise<CreateMetricResponse>

Create a new metric

delete

delete(request: DeleteMetricRequest): Promise<DeleteMetricResponse>

Delete a metric

list

list(request?: GetMetricsRequest): Promise<GetMetricsResponse>

List all metrics

run

run(request: RunMetricRequest): Promise<RunMetricResponse>

Run a metric evaluation Execute a metric on a specific event

update

update(request: UpdateMetricRequest): Promise<UpdateMetricResponse>

Update an existing metric Update a metric’s editable fields. Only fields included in the request body are modified.

sessions

create

create(request: CreateSessionRequest): Promise<CreateSessionResponse>

Start a new session Start a new session. The request body is a bare session object (no session wrapper). The server creates a session event and returns it. No required properties. Every field has a server-side fallback. Auto-generated properties (provided by the server when omitted):

session_id (string, UUID): Server generates a UUIDv4 if omitted or if the supplied value is not a valid UUID.

Optional properties with defaults:

event_name (string): Falls back to session_name when not provided; defaults to "unknown" if both are absent.
source (string): Defaults to "unknown".

Optional properties:

session_name (string): Display name for the session.
start_time (number): Session start time as Unix milliseconds. The session normalizer uses getInt64() which only accepts numeric types; if a string is passed, the server silently falls back to the current time.
end_time (number): Session end time as Unix milliseconds (same numeric-only caveat as start_time).
duration (number): Session duration in milliseconds.
config (object): Configuration associated with the session.
inputs (object): Input data for the session.
outputs (object): Output data from the session.
metadata (object): Arbitrary metadata.
user_properties (object): User properties.
children_ids (array of strings): IDs of child events.

Idempotent on session_id: posting twice with the same session_id merges metadata/user_properties into the existing session and returns the existing event.

createEventBatch

createEventBatch(request: CreateSessionEventBatchRequest): Promise<CreateSessionEventBatchResponse>

Add a batch of events to a session Add a batch of events to an existing session. Each event in the batch is stored with session_id set from the URL path, overriding any session_id in the event body. Each event must include event_type (one of chain, model, tool, session) and inputs. Unknown top-level fields and unknown per-event fields are rejected. Events are processed sequentially. For higher-throughput ingestion across sessions, use POST /v1/events/batch instead.

Example response

{
  "success": true
}

​Constructor

​Namespaces

​charts

​create

​delete

​get

​list

​update

​datapoints

​create

​createBatch

​delete

​get

​list

​update

​datasets

​addDatapoints

​create

​delete

​list

​removeDatapoint

​update

​events

​create

Example response

​createBatch

Example response

​search

​update

Example request

​experiments

​compareRunEvents

​compareRuns

​createRun

​deleteRun

​getRun

​getRunMetrics

​getRunSchema

​getRunsSchema

​getSummary

​listRuns

​updateRun

​metricVersions

​create

​deploy

​list

​metrics

​create

​delete

​list

​run

​update

​sessions

​create

​createEventBatch

Example response

Constructor

Namespaces

charts

create

delete

get

list

update

datapoints

create

createBatch

delete

get

list

update

datasets

addDatapoints

create

delete

list

removeDatapoint

update

events

create

createBatch

search

update

experiments

compareRunEvents

compareRuns

createRun

deleteRun

getRun

getRunMetrics

getRunSchema

getRunsSchema

getSummary

listRuns

updateRun

metricVersions

create

deploy

list

metrics

create

delete

list

run

update

sessions

create

createEventBatch