chore(release): Release v1.3.0

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-06-18
+
+### Added
+
+- **Configurable API request timeout**
+  - `HoneyHive(timeout=...)` now sets the per-request timeout, in seconds, for standard API client calls. You can also set `HH_API_TIMEOUT`; the explicit `timeout=` argument takes precedence. The default remains 5 seconds, so existing clients keep the same timeout unless you opt in.
+- **Event lookup by ID**
+  - The generated sync and async event services now include `GET /v1/events/{event_id}` as `getEvent(..., event_id=...)`, returning `GetEventResponse` / `GetEventResponseEvent` models exported from `honeyhive.models`.
+- **Custom tracer export HTTP sessions**
+  - `HoneyHiveTracer.init(requests_session=...)` and `TracerConfig(requests_session=...)` now accept a caller-owned `requests.Session` for OTLP span export. Use this when you need custom proxies, retries, TLS settings, or connection pooling. The SDK does not close a session that you provide.
+
+### Compatibility
+
+- **Self-host: `GET /v1/events/{event_id}` requires backend v1.3.0+**
+  - Self-hosted deployments must run a HoneyHive backend on version 1.3.0 or greater before calling `GET /v1/events/{event_id}`. Older self-host backends do not expose this route, so event-by-id calls will fail until the backend is upgraded. HoneyHive Cloud users are unaffected.
+
 ## [1.2.1] - 2026-06-11
 
 No customer-facing changes. Internal OpenAPI generator and generated-model cleanup only.

openapi/dataplane.yaml

@@ -4,7 +4,7 @@ info:
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
-  version: 1.1.0
+  version: 1.2.1
 servers:
   - url: https://api.honeyhive.ai
 tags:
@@ -335,6 +335,35 @@ paths:
         '400':
           description: Bad request (invalid event data or missing required fields)
   /v1/events/{event_id}:
+    get:
+      tags:
+        - Events
+      operationId: getEvent
+      x-cli-name: get
+      x-ts-sdk-name: get
+      summary: Get an event by ID
+      description: |
+        Retrieve a single event by its unique identifier. The event is fetched
+        directly from S3/MinIO storage.
+      parameters:
+        - in: path
+          name: event_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: The unique identifier of the event to retrieve
+      responses:
+        '200':
+          description: Event retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GetEventResponse'
+        '400':
+          description: Bad request (invalid event_id)
+        '404':
+          description: Event not found
     put:
       tags:
         - Events
@@ -2282,6 +2311,72 @@ components:
       type: http
       scheme: bearer
   schemas:
+    SingleFilter:
+      type: object
+      properties:
+        field:
+          type: string
+        operator:
+          type: string
+          enum:
+            - exists
+            - not exists
+            - is
+            - is not
+            - contains
+            - not contains
+            - greater than
+            - less than
+            - after
+            - before
+        value:
+          anyOf:
+            - type: string
+            - type: number
+            - type: boolean
+            - type: 'null'
+        type:
+          type: string
+          enum:
+            - string
+            - number
+            - boolean
+            - datetime
+      required:
+        - field
+        - operator
+        - value
+        - type
+    Pagination:
+      type: object
+      properties:
+        page:
+          type: integer
+          minimum: 1
+        limit:
+          type: integer
+          minimum: 1
+        total:
+          type: integer
+          minimum: 0
+        total_unfiltered:
+          type: integer
+          minimum: 0
+        total_pages:
+          type: integer
+          minimum: 0
+        has_next:
+          type: boolean
+        has_prev:
+          type: boolean
+      required:
+        - page
+        - limit
+        - total
+        - total_unfiltered
+        - total_pages
+        - has_next
+        - has_prev
     CreateChartRequest:
       type: object
       properties:
@@ -3235,42 +3330,6 @@ components:
         - dereferenced
         - message
       description: Response for DELETE /datasets/{dataset_id}/datapoints/{datapoint_id}
-    SingleFilter:
-      type: object
-      properties:
-        field:
-          type: string
-        operator:
-          type: string
-          enum:
-            - exists
-            - not exists
-            - is
-            - is not
-            - contains
-            - not contains
-            - greater than
-            - less than
-            - after
-            - before
-        value:
-          anyOf:
-            - type: string
-            - type: number
-            - type: boolean
-            - type: 'null'
-        type:
-          type: string
-          enum:
-            - string
-            - number
-            - boolean
-            - datetime
-      required:
-        - field
-        - operator
-        - value
-        - type
     FiltersArray:
       type: array
       items:
@@ -3921,6 +3980,14 @@ components:
         - events
         - totalEvents
       description: Response for GET /events
+    GetEventResponse:
+      type: object
+      properties:
+        event:
+          $ref: '#/components/schemas/GetEventResponseEvent'
+      required:
+        - event
+      description: Response for GET /events/:event_id — single event payload
     ExportEventsResponse:
       type: object
       properties:
@@ -3949,36 +4016,6 @@ components:
         - event_ids
         - success
       description: Response for POST /events/batch
-    Pagination:
-      type: object
-      properties:
-        page:
-          type: integer
-          minimum: 1
-        limit:
-          type: integer
-          minimum: 1
-        total:
-          type: integer
-          minimum: 0
-        total_unfiltered:
-          type: integer
-          minimum: 0
-        total_pages:
-          type: integer
-          minimum: 0
-        has_next:
-          type: boolean
-        has_prev:
-          type: boolean
-      required:
-        - page
-        - limit
-        - total
-        - total_unfiltered
-        - total_pages
-        - has_next
-        - has_prev
     PassingRange:
       type: object
       properties:
@@ -6179,6 +6216,89 @@ components:
       required:
         - $gte
         - $lte
+    GetEventResponseEvent:
+      type: object
+      properties:
+        project:
+          type: string
+          deprecated: true
+          description: Project name (ignored by server — project is determined from API key scope)
+        project_id:
+          type: string
+          description: Project ID
+        source:
+          type: string
+          description: Source of the event (e.g., sdk-python)
+        event_name:
+          type: string
+          description: Name of the event
+        event_type:
+          type: string
+          enum:
+            - model
+            - tool
+            - chain
+            - session
+          description: Type of event (model, tool, chain, or session)
+        event_id:
+          type: string
+        session_id:
+          type: string
+          description: Session this event belongs to
+        parent_id:
+          type: string
+          description: Parent event ID in the trace hierarchy
+        children_ids:
+          type: array
+          items:
+            type: string
+          description: Child event IDs in the trace hierarchy
+        config:
+          type: object
+          additionalProperties: {}
+          description: Configuration used for this event
+        inputs:
+          type: object
+          additionalProperties: {}
+          description: Input data for the event
+        outputs:
+          type: object
+          additionalProperties: {}
+          description: Output data from the event
+        error:
+          type:
+            - string
+            - 'null'
+          description: Error message if the event failed
+        start_time:
+          type: number
+          description: Event start time as Unix milliseconds
+        end_time:
+          type: number
+          description: Event end time as Unix milliseconds
+        duration:
+          type: number
+          description: Event duration in milliseconds
+        metadata:
+          type: object
+          additionalProperties: {}
+          description: Arbitrary metadata for the event
+        feedback:
+          type: object
+          additionalProperties: {}
+          description: Feedback data associated with the event
+        metrics:
+          type: object
+          additionalProperties: {}
+          description: Metric values computed for the event
+        user_properties:
+          type: object
+          additionalProperties: {}
+          description: User properties associated with the event
+      required:
+        - event_id
+      additionalProperties: {}
+      description: Full event object for legacy event creation endpoints
     EventMetricDataMetadata:
       type: object
       properties:

scripts/templates/apiconfig_pydantic_2.jinja2

@@ -10,6 +10,8 @@
   - Removed env_token_name conditional branches (hardcoded to the non-env-token path)
   - Added _serialize_query_params() helper so List-typed query params are sent as
     bracket notation (ids[]=a&ids[]=b) instead of bare repeated keys (ids=a&ids=b)
+  - Added a configurable `timeout` field (defaults to 5.0s, matching httpx's own
+    default) plumbed through to the httpx clients
 #}
 import os
 from typing import Any, Dict, Optional, Union
@@ -31,6 +33,10 @@ class APIConfig(BaseModel):
     base_path: str = DEFAULT_BASE_URL
     verify: Union[bool, str] = True
     access_token: Optional[str] = None
+    # Request timeout in seconds passed to the underlying httpx client. Defaults
+    # to 5.0 to match httpx's own default (so behaviour is unchanged unless set).
+    # Set to None to disable timeouts entirely.
+    timeout: Optional[float] = 5.0
 
     @classmethod
     def from_env(

scripts/templates/httpx.jinja2

@@ -8,6 +8,8 @@
     notation to recognise a single-value list as an array rather than a string.
   - data.dict() replaced with data.model_dump(exclude_none=True) for Pydantic v2
     compatibility and to avoid sending null fields to the API.
+  - timeout=api_config.timeout passed to the httpx client so the request timeout
+    is configurable via APIConfig (defaults to 5.0s, matching httpx's default).
 #}
 {%  if async_client %}async {% endif %}def {{ operation_id }}(api_config_override : Optional[APIConfig] = None{% if params.strip() %}, *, {{ params.rstrip(', ') }}{% endif %}) -> {% if return_type.type is none or return_type.type.converted_type is none %}None{% else %}{{ return_type.type.converted_type}}{% endif %}:
     api_config = api_config_override if api_config_override else APIConfig()
@@ -29,10 +31,10 @@
     query_params = {key:value for (key,value) in query_params.items() if value is not None}
 
     {% if async_client %}
-async with httpx.AsyncClient(base_url=base_path, verify=api_config.verify) as client:
+async with httpx.AsyncClient(base_url=base_path, verify=api_config.verify, timeout=api_config.timeout) as client:
         response = await client.request(
     {% else %}
-with httpx.Client(base_url=base_path, verify=api_config.verify) as client:
+with httpx.Client(base_url=base_path, verify=api_config.verify, timeout=api_config.timeout) as client:
         response = client.request(
     {% endif %}
         '{{ method }}',

src/honeyhive/__init__.py

@@ -5,7 +5,7 @@
 # Version must be defined BEFORE imports to avoid circular import issues
 # Version must be semver or semver followed by "a" (alpha), "b" (beta), or "rc"
 # (release candidate) + a number
-__version__ = "1.2.1"
+__version__ = "1.3.0"
 
 # Main API client
 from .api import HoneyHive

src/honeyhive/_generated/api_config.py

@@ -15,6 +15,10 @@ class APIConfig(BaseModel):
     base_path: str = DEFAULT_BASE_URL
     verify: Union[bool, str] = True
     access_token: Optional[str] = None
+    # Request timeout in seconds passed to the underlying httpx client. Defaults
+    # to 5.0 to match httpx's own default (so behaviour is unchanged unless set).
+    # Set to None to disable timeouts entirely.
+    timeout: Optional[float] = 5.0
 
     @classmethod
     def from_env(