Events - HoneyHive AI Docs

Schema introspection

Every command below with arguments supports two read-only flags for tooling and AI agents:

--show-file-schema: print the JSON Schema for the full request object (the format --filename accepts).
--show-argument-schema <flag-name>: print the JSON Schema for one argument’s value. Pass the kebab flag name without the leading -- (e.g. project-id, not --project-id).

Both write pure JSON to stdout and never call the API. They cannot be combined with any other command-specific flag.

`create`

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.

Usage

honeyhive events create [options]

Options

Flag	Type	Required	Description
`--event-type`	string	yes	Type of event (model, tool, chain, or session) Allowed: `model`, `tool`, `chain`, `session`.
`--inputs`	json	yes	Input data for the event
`--children-ids`	json	no	Child event IDs in the trace hierarchy
`--config`	json	no	Configuration used for this event
`--duration`	number	no	Event duration in milliseconds
`--end-time`	number	no	Event end time as Unix milliseconds
`--error`	string	no	Error message if the event failed
`--event-id`	string	no	Unique event identifier
`--event-name`	string	no	Name of the event
`--feedback`	json	no	Feedback data associated with the event
`--metadata`	json	no	Arbitrary metadata for the event
`--metrics`	json	no	Metric values computed for the event
`--outputs`	json	no	Output data from the event
`--parent-id`	string	no	Parent event ID in the trace hierarchy
`--project-id`	string	no	Project ID
`--session-id`	string	no	Session this event belongs to
`--source`	string	no	Source of the event (e.g., sdk-python)
`--start-time`	number	no	Event start time as Unix milliseconds
`--user-properties`	json	no	User properties associated with the event

Also supports --show-file-schema, --show-argument-schema <flag-name>, and --filename. See Schema introspection for details.

Example response

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

`get`

Get an event by ID Retrieve a single event by its unique identifier. The event is fetched directly from S3/MinIO storage.

Usage

honeyhive events get [options]

Options

Flag	Type	Required	Description
`--event-id`	string	yes	The unique identifier of the event to retrieve

Also supports --show-file-schema, --show-argument-schema <flag-name>, and --filename. See Schema introspection for details.

`update`

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.

Usage

honeyhive events update [options]

Options

Flag	Type	Required	Description
`--event-id`	string	yes	The unique identifier of the event to update
`--children-ids`	json	no	IDs of child events to set (must be non-empty; an empty array is ignored)
`--config`	json	no	Configuration fields to merge into the event
`--duration`	number	no	Event duration in milliseconds
`--end-time`	number	no	Unix timestamp in milliseconds for event end
`--feedback`	json	no	Feedback fields to merge into the event
`--metadata`	json	no	Metadata fields to merge into the event
`--metrics`	json	no	Metric values to merge into the event
`--outputs`	json	no	Output object to replace on the event. Must be an object or null; null preserves the existing outputs. Non-object values (strings, arrays, scalars) are rejected.
`--user-properties`	json	no	User properties to merge into the event

Also supports --show-file-schema, --show-argument-schema <flag-name>, and --filename. See Schema introspection for details.

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
}

`search`

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

Usage

honeyhive events search [options]

Options

Flag	Type	Required	Description
`--date-range`	json	no	dateRange
`--evaluation-id`	string	no	Filter by evaluation/experiment run ID
`--filters`	json	no	filters
`--ignore-order` / `--no-ignore-order`	boolean	no	Deprecated: accepted but ignored. Results are always ordered by start_time descending.
`--limit`	number	no	Limit number of results (default 1000, max 1000)
`--page`	number	no	Page number of results (default 1)

Also supports --show-file-schema, --show-argument-schema <flag-name>, and --filename. See Schema introspection for details.

`create-batch`

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.

Usage

honeyhive events create-batch [options]

Options

Flag	Type	Required	Description
`--events`	json	yes	Array of events to create
`--session-properties`	json	no	Session properties for batch event creation
`--single-session` / `--no-single-session`	boolean	no	If true, all events share the same session

Also supports --show-file-schema, --show-argument-schema <flag-name>, and --filename. See Schema introspection for details.

Example response

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

​Schema introspection

​create

​Usage

​Options

​Example response

​get

​Usage

​Options

​update

​Usage

​Options

​Example request

​search

​Usage

​Options

​create-batch

​Usage

​Options

​Example response

Schema introspection

`create`

Usage

Options

Example response

`get`

Usage

Options

`update`

Usage

Options

Example request

`search`

Usage

Options

`create-batch`

Usage

Options

Example response