Skip to main content

​
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

FlagTypeRequiredDescription
--event-typestringyesType of event (model, tool, chain, or session) Allowed: model, tool, chain, session.
--inputsjsonyesInput data for the event
--children-idsjsonnoChild event IDs in the trace hierarchy
--configjsonnoConfiguration used for this event
--durationnumbernoEvent duration in milliseconds
--end-timenumbernoEvent end time as Unix milliseconds
--errorstringnoError message if the event failed
--event-idstringnoUnique event identifier
--event-namestringnoName of the event
--feedbackjsonnoFeedback data associated with the event
--metadatajsonnoArbitrary metadata for the event
--metricsjsonnoMetric values computed for the event
--outputsjsonnoOutput data from the event
--parent-idstringnoParent event ID in the trace hierarchy
--project-idstringnoProject ID
--session-idstringnoSession this event belongs to
--sourcestringnoSource of the event (e.g., sdk-python)
--start-timenumbernoEvent start time as Unix milliseconds
--user-propertiesjsonnoUser 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
}

​
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

FlagTypeRequiredDescription
--event-idstringyesThe unique identifier of the event to update
--children-idsjsonnoIDs of child events to set (must be non-empty; an empty array is ignored)
--configjsonnoConfiguration fields to merge into the event
--durationnumbernoEvent duration in milliseconds
--end-timenumbernoUnix timestamp in milliseconds for event end
--feedbackjsonnoFeedback fields to merge into the event
--metadatajsonnoMetadata fields to merge into the event
--metricsjsonnoMetric values to merge into the event
--outputsjsonnoOutput data to replace on the event (accepts objects, strings, arrays, or scalars)
--user-propertiesjsonnoUser 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
}
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

FlagTypeRequiredDescription
--date-rangejsonnodateRange
--evaluation-idstringnoFilter by evaluation/experiment run ID
--filtersjsonnofilters
--ignore-order / --no-ignore-orderbooleannoDeprecated: accepted but ignored. Results are always ordered by start_time descending.
--limitnumbernoLimit number of results (default 1000, max 1000)
--pagenumbernoPage 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

FlagTypeRequiredDescription
--eventsjsonyesArray of events to create
--session-propertiesjsonnoSession properties for batch event creation
--single-session / --no-single-sessionbooleannoIf 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
}