> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events Methods

> Read and write HoneyHive trace events through the TypeScript Events namespace with typed create, batch ingest, search, and update API methods.

#### create

> **create**(`request`: [`CreateEventRequest`](/v2/sdk-reference/typescript/ref/events/CreateEventRequest)): `Promise`\<[`CreateEventResponse`](/v2/sdk-reference/typescript/ref/events/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

```json theme={null}
{
  "event_id": "7f22137a-6911-4ed3-bc36-110f1dde6b66",
  "success": true
}
```

#### createBatch

> **createBatch**(`request`: [`CreateEventBatchRequest`](/v2/sdk-reference/typescript/ref/events/CreateEventBatchRequest)): `Promise`\<[`CreateEventBatchResponse`](/v2/sdk-reference/typescript/ref/events/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

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

#### get

> **get**(`request`: [`GetEventRequest`](/v2/sdk-reference/typescript/ref/events/GetEventRequest)): `Promise`\<[`GetEventResponse`](/v2/sdk-reference/typescript/ref/events/GetEventResponse)>

Get an event by ID

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

#### search

> **search**(`request`: [`SearchEventsRequest`](/v2/sdk-reference/typescript/ref/events/SearchEventsRequest)): `Promise`\<[`SearchEventsResponse`](/v2/sdk-reference/typescript/ref/events/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`](/v2/sdk-reference/typescript/ref/events/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

```json theme={null}
{
  "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
}
```