> ## 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.

# Clients

> Releases for the Python SDK, TypeScript API SDK, and CLI.

{/*
A single pill in the filter bar. Rendered four times by `Filter` to form a
joined pill group. The `isFirst` / `isLast` props handle the rounded outer
corners — Mintlify's Tailwind build doesn't seem to compile arbitrary-variant
selectors like `[&>button:first-child]:rounded-l-xl`, so we pass position as
a prop rather than relying on CSS sibling selectors. Active state mirrors the
"Log In" CTA in the topbar; inactive mirrors the "Community" link.
*/}

export const FilterButton = ({children, isActive = false, isFirst = false, isLast = false, onClick}) => {
  const base = "px-4 py-1.5 text-sm font-medium inline-flex items-center whitespace-nowrap transition-colors";
  const active = "bg-primary-dark text-white";
  const inactive = "bg-gray-950/5 dark:bg-white/5 text-gray-950/70 dark:text-white/70 hover:bg-gray-950/10 dark:hover:bg-white/10";
  const radius = [isFirst && "rounded-l-xl", isLast && "rounded-r-xl"].filter(Boolean).join(" ");
  return <button className={`${base} ${radius} ${isActive ? active : inactive}`} onClick={onClick}>
      {children}
    </button>;
};

export const applyFilter = filter => {
  const containers = document.querySelectorAll('.update-container');
  for (const container of containers) {
    const entries = container.querySelectorAll('.hh-update-entry');
    let firstVisible = null;
    for (const entry of entries) {
      const matches = filter === "all" || entry.dataset.filter === filter;
      entry.style.display = matches ? "" : "none";
      const h2 = entry.querySelector('h2');
      if (h2) h2.style.marginTop = "";
      if (matches && !firstVisible) firstVisible = entry;
    }
    if (firstVisible) {
      const h2 = firstVisible.querySelector('h2');
      if (h2) h2.style.marginTop = "0";
      container.style.display = "";
    } else {
      container.style.display = "none";
    }
  }
};

export const Filter = () => {
  const DEFAULT_FILTER = "all";
  const [isSkeletonHidden, setIsSkeletonHidden] = useState(false);
  const [activeFilter, setActiveFilter] = useState(DEFAULT_FILTER);
  useEffect(() => {
    if (!isSkeletonHidden) {
      const skeleton = document.querySelector('.filter-skeleton');
      if (skeleton) skeleton.style.display = "none";
      setIsSkeletonHidden(true);
    } else {
      applyFilter(DEFAULT_FILTER);
    }
  }, [isSkeletonHidden]);
  const onSelect = filter => {
    setActiveFilter(filter);
    applyFilter(filter);
  };
  if (!isSkeletonHidden) {
    return null;
  }
  return <div className="flex items-center">
      <FilterButton isActive={activeFilter === "all"} isFirst onClick={() => onSelect("all")}>All</FilterButton>
      <FilterButton isActive={activeFilter === "python"} onClick={() => onSelect("python")}>Python SDK</FilterButton>
      <FilterButton isActive={activeFilter === "typescript"} onClick={() => onSelect("typescript")}>TypeScript API SDK</FilterButton>
      <FilterButton isActive={activeFilter === "cli"} isLast onClick={() => onSelect("cli")}>CLI</FilterButton>
    </div>;
};

<div style={{minHeight: "2.25rem"}}>
  <div className="filter-skeleton flex items-center">
    <button disabled className="px-4 py-1.5 text-sm font-medium inline-flex items-center whitespace-nowrap rounded-l-xl bg-primary-dark text-white cursor-not-allowed">All</button>
    <button disabled className="px-4 py-1.5 text-sm font-medium inline-flex items-center whitespace-nowrap bg-gray-950/5 dark:bg-white/5 text-gray-950/70 dark:text-white/70 cursor-not-allowed">Python SDK</button>
    <button disabled className="px-4 py-1.5 text-sm font-medium inline-flex items-center whitespace-nowrap bg-gray-950/5 dark:bg-white/5 text-gray-950/70 dark:text-white/70 cursor-not-allowed">TypeScript API SDK</button>
    <button disabled className="px-4 py-1.5 text-sm font-medium inline-flex items-center whitespace-nowrap rounded-r-xl bg-gray-950/5 dark:bg-white/5 text-gray-950/70 dark:text-white/70 cursor-not-allowed">CLI</button>
  </div>

  <Filter />
</div>

<Update label="May 29th, 2026">
  <div data-filter="typescript" className="hh-update-entry">
    ## TypeScript API SDK

    ### [v1.3.0](https://github.com/honeyhiveai/typescript-api-client/releases/tag/v1.3.0)

    #### What's New

    * New `client.metricVersions` namespace with `list`, `create`, and `deploy` methods for managing snapshot versions of a metric's definition via `/v1/metrics/{metric_id}/versions` and `/v1/metrics/{metric_id}/versions/{version_name}/deploy`.
    * New exported request/response types: `GetMetricVersionsRequest`/`Response`, `CreateMetricVersionRequest`/`Response`, and `DeployMetricVersionRequest`/`Response`.
  </div>

  <div data-filter="cli" className="hh-update-entry">
    ## CLI

    ### [v1.3.0](https://github.com/honeyhiveai/honeyhive-cli/releases/tag/v1.3.0)

    #### What's New

    * Added `metric-versions` subcommands for managing snapshot versions of a metric's definition: `metric-versions list`, `metric-versions create`, and `metric-versions deploy`. Use these to review history, create new draft or immediately-deployed versions, and roll between versions without losing history.
  </div>
</Update>

<Update label="May 22nd, 2026">
  <div data-filter="typescript" className="hh-update-entry">
    ## TypeScript API SDK

    ### [v1.2.1](https://github.com/honeyhiveai/typescript-api-client/releases/tag/v1.2.1)

    Internal improvements only.
  </div>

  <div data-filter="cli" className="hh-update-entry">
    ## CLI

    ### [v1.2.1](https://github.com/honeyhiveai/honeyhive-cli/releases/tag/v1.2.1)

    Internal improvements only.
  </div>
</Update>

<Update label="May 21st, 2026">
  <div data-filter="typescript" className="hh-update-entry">
    ## TypeScript API SDK

    ### [v1.2.0](https://github.com/honeyhiveai/typescript-api-client/releases/tag/v1.2.0)

    #### What's New

    * Added a `dataPlaneUrl` client option and `HH_DATA_PLANE_URL` environment variable for configuring the data plane URL. These replace the previous `serverUrl` option and `HH_API_URL` environment variable.
    * The verbose logging output now labels the resolved URL as `Data plane URL:` (previously `API URL:`).

    #### Fixes & Improvements

    * Environment variables set to the empty string (e.g. `HH_API_KEY=`, `HH_DATA_PLANE_URL=`) are now treated as unset and fall back to defaults, rather than being propagated as a literal empty string.

    #### Compatibility & Deprecations

    * The `serverUrl` client option and `HH_API_URL` environment variable are deprecated and will be removed in the next major version. They continue to work but log a one-time deprecation warning to stderr on client construction. Migrate to `dataPlaneUrl` / `HH_DATA_PLANE_URL`.
  </div>

  <div data-filter="cli" className="hh-update-entry">
    ## CLI

    ### [v1.2.0](https://github.com/honeyhiveai/honeyhive-cli/releases/tag/v1.2.0)

    #### What's New

    * Added `--data-plane-url` flag and `HH_DATA_PLANE_URL` environment variable for pointing the CLI at a specific HoneyHive data plane (e.g. self-hosted or staging deployments). Verbose output now labels this value as `Data plane URL:` instead of `API URL:`.

    #### Compatibility & Deprecations

    * The `--base-url` flag and `HH_API_URL` environment variable are deprecated and will be removed in the next major version. They still work as aliases for the new names but now log a deprecation warning to stderr on each invocation. Migrate to `--data-plane-url` / `HH_DATA_PLANE_URL`.
  </div>
</Update>

<Update label="May 19th, 2026">
  <div data-filter="typescript" className="hh-update-entry">
    ## TypeScript API SDK

    ### [v1.1.1](https://github.com/honeyhiveai/typescript-api-client/releases/tag/v1.1.1)

    #### Fixes & Improvements

    * Fixed a bug where `error.message` on thrown API errors was not populated, causing error logs and CLI output to omit the underlying failure detail.
  </div>

  <div data-filter="cli" className="hh-update-entry">
    ## CLI

    ### [v1.1.1](https://github.com/honeyhiveai/honeyhive-cli/releases/tag/v1.1.1)

    #### Fixes & Improvements

    * Error output for failed API requests now includes the server's error message. All CLI commands that hit the API previously printed only `API error <status>`; they now print `API error <status>: <message>` with the actionable detail from the server.
  </div>

  <div data-filter="python" className="hh-update-entry">
    ## Python SDK

    ### [v1.1.0](https://github.com/honeyhiveai/python-sdk/releases/tag/v1.1.0)

    #### Added

    * **Charts API: `client.charts` CRUD surface**
      * New `client.charts.create()`, `.list()`, `.get(chart_id)`, `.update(chart_id, request)`, and `.delete(chart_id)` methods (plus `*_async` variants) backed by `POST /v1/charts`, `GET /v1/charts`, `GET /v1/charts/{chart_id}`, `PUT /v1/charts/{chart_id}`, and `DELETE /v1/charts/{chart_id}`. Chart request and response models are exported from `honeyhive.models`.

    #### Changed

    * **CrewAI integration example refreshed**
      * The CrewAI example (`examples/integrations/crewai_integration.py`) has been rewritten with three realistic customer-support scenarios (single-agent with tool calls, sequential two-agent crew, and `@trace` escalation). Crews are now named for clearer span labels, and teardown properly flushes remaining spans.

    #### Fixed

    * **Tracer init: `project` / `HH_PROJECT` no longer required**
      * `HoneyHiveTracer.init()` previously required `project` and treated a missing value as degraded mode. Since the backend determines the project from the API key, only `api_key` is actually needed. Callers that followed the v1.0.1 deprecation guidance and removed `project` were silently running in degraded mode — this is now fixed. `project` and `HH_PROJECT` remain accepted for backwards compatibility (deprecated, to be removed in v2.0).

    * **Duplicate `model` spans in `evaluate()`**
      * `evaluate()` could occasionally emit two `model` spans for a single LLM call when running multiple datapoints concurrently. The underlying race condition in instrumentation setup has been fixed.

    #### Removed

    * **`cp_base_url=` parameter and `HH_CP_API_URL` env var removed**
      * These options were vestigial configuration for an incomplete Control Plane integration that was never wired up or shipped. No customer code could have depended on them. They have been removed to clean up the public API surface. If you happen to pass `cp_base_url=` or set `HH_CP_API_URL`, simply remove them — `HH_API_URL` / `base_url=` is the only base-URL setting.
  </div>
</Update>

<Update label="May 15th, 2026">
  <div data-filter="typescript" className="hh-update-entry">
    ## TypeScript API SDK

    ### [v1.1.0](https://github.com/honeyhiveai/typescript-api-client/releases/tag/v1.1.0)

    #### What's New

    * New `client.charts` namespace with `create`, `list`, `get`, `update`, and `delete` methods for managing charts via `/v1/charts` and `/v1/charts/{chart_id}`.
    * New `client.experiments.getSummary()` method for `GET /v1/runs/{run_id}/summary`, returning pass/fail results, metric aggregations, per-datapoint results, and the experiment run object.
    * New `client.sessions.createEventBatch()` method for `POST /v1/sessions/{session_id}/events/batch`, accepting a batch of events scoped to a single session (the `session_id` from the path overrides any value in the event body).
    * New exported request/response types: `CreateChartRequest`/`Response`, `GetChartRequest`/`Response`, `GetChartsResponse`, `UpdateChartRequest`/`Response`, `DeleteChartRequest`/`Response`, `GetExperimentSummaryRequest`/`Response`, and `CreateSessionEventBatchRequest`/`Response`.

    #### Compatibility & Deprecations

    * Bumped `axios` from `1.15.2` to `1.16.0`.
  </div>

  <div data-filter="cli" className="hh-update-entry">
    ## CLI

    ### [v1.1.0](https://github.com/honeyhiveai/honeyhive-cli/releases/tag/v1.1.0)

    #### What's New

    * Added `charts` subcommands for managing charts via the CLI: `charts list`, `charts create`, `charts get`, `charts update`, and `charts delete`.
    * Added `sessions create-event-batch` for adding a batch of events to an existing session.
    * Added `experiments get-summary` for retrieving an experiment run's evaluation summary, including pass/fail results and metric aggregations.
  </div>
</Update>

<Update label="May 11th, 2026">
  <div data-filter="python" className="hh-update-entry">
    ## Python SDK

    ### [v1.0.2](https://github.com/honeyhiveai/python-sdk/releases/tag/v1.0.2)

    #### Fixed

    * **Experiments: client-side evaluator scores now flow end-to-end in `evaluate()`**
      * Scores returned by evaluators in `evaluate()` are now written to the correct user-function chain span via `enrich_span(metrics=…)`, exported over OTLP, and surfaced in server-side run comparison's per-event `metric_deltas`. Previously, evaluator scores were duplicated into `run.metadata.evaluator_metrics` and onto the per-datapoint session event, but neither path actually populated the per-event surface that run comparison requires — client-side evaluator scoring and comparison did not work end-to-end.
      * The two legacy write paths have been removed now that the scores are correctly written to the chain span as the single source of truth.

    * **API Client: `event_id` typed as required on `POST /events` responses**
      * `PostEventResponse.event_id` was incorrectly typed as `Optional[str]` in the OpenAPI spec; the backend always returns the field on a 2xx response. The spec was corrected and the generated SDK now reflects the runtime guarantee, removing the need for defensive `if event.event_id:` guards. No runtime behavior change, but strictly typed mypy codebases with `warn_unreachable = True` or pyright with `reportUnnecessaryComparison` enabled may produce "unnecessary comparison" or "redundant Optional guard" warnings, depending on exact usage patterns.

    #### Added

    * **`FilterFieldType.DATETIME` enum value**
      * The SDK enum was missing the `"datetime"` wire value supported by the backend. Additive — no behavior change for existing callers.

    #### Deprecated

    * **`FilterFieldType.ID`**
      * `ID = "id"` was never a valid backend wire value and has always been rejected on the wire. Use `"string"` for UUID-shaped fields such as `session_id`. The alias is preserved so existing imports continue to resolve and will be removed in the next major.

    #### Removed

    * **`honeyhive` Python CLI entry point removed from `pyproject.toml`**
      * The shipped Python `honeyhive` console script was non-functional (dead code) and shadowed the official TypeScript CLI on `$PATH`. CLI functionality is now provided by the official [`honeyhive` TypeScript CLI](https://docs.honeyhive.ai/v2/cli-reference); removing the Python script entry point lets `honeyhive` resolve correctly when both packages are installed globally.
  </div>

  <div data-filter="typescript" className="hh-update-entry">
    ## TypeScript API SDK

    ### [v1.0.1](https://github.com/honeyhiveai/typescript-api-client/releases/tag/v1.0.1)

    Internal improvements only.
  </div>

  <div data-filter="typescript" className="hh-update-entry">
    ## TypeScript API SDK

    ### [v1.0.0](https://github.com/honeyhiveai/typescript-api-client/releases/tag/v1.0.0)

    Initial launch.
  </div>

  <div data-filter="cli" className="hh-update-entry">
    ## CLI

    ### [v1.0.0](https://github.com/honeyhiveai/honeyhive-cli/releases/tag/v1.0.0)

    Initial launch
  </div>
</Update>

<Update label="May 5th, 2026">
  <div data-filter="python" className="hh-update-entry">
    ## Python SDK

    ### [v1.0.1](https://github.com/honeyhiveai/python-sdk/releases/tag/v1.0.1)

    #### Fixed

    * **Default API URL fallback corrected to `https://api.dp1.us.honeyhive.ai`**
      * The fallback value for the base API URL in the v1.0.0 release was incorrect. Any callers who relied on the implicit default would fail. The default now points at the host the SDK is built against, though self-hosted / non-default Data Plane deployments will still need to set `HH_API_URL` explicitly. Callers that explicitly set `base_url=` / `server_url=` or `HH_API_URL` are unaffected.

    #### Deprecated

    * **`project` argument and `HH_PROJECT` environment variable**
      * The SDK's public surface has accepted `project=` on `HoneyHive()` and `HoneyHiveTracer.init()` and the `HH_PROJECT` env var for historical reasons. These arguments and env vars have no influence on the backend and they were maintained purely for backwards compatibility of callers. This release sweeps the stale references out of the example scripts, README, and docstrings, and adds a `DeprecationWarning` at the remaining call sites that previously didn't emit one. The argument and the `HH_PROJECT` env var alias **remain** accepted for backwards compatibility and will be removed in v2.0.
  </div>
</Update>

<Update label="May 4th, 2026">
  <div data-filter="python" className="hh-update-entry">
    ## Python SDK

    ### [v1.0.0](https://github.com/honeyhiveai/python-sdk/releases/tag/v1.0.0)

    First stable GA release of the HoneyHive Python SDK. Public APIs follow semver from this release forward — breaking changes only on major versions, additive on minor and patch.

    The changes below are relative to `1.0.0rc22`. For the full picture of what shipped during the release-candidate cycle, see the `1.0.0rc1`–`1.0.0rc22` entries.

    #### Changed

    * **Tracing: `skip_backend_session_creation=True` now works without an explicit `session_id`**
      * Previously the flag only opted out of the init-time backend roundtrip when a `session_id` was also supplied. Setting the flag alone is now supported: the SDK skips the roundtrip, does not mint a UUID, and per-request `create_session(session_id=..., skip_api_call=True)` calls emit spans that ingestion materializes into Session rows on first arrival.

    * **Tracing: `create_session(skip_api_call=True)` propagates `session_name` into baggage**
      * When `session_name` is supplied, it now travels with `session_id` across async / threaded boundaries.

    #### Removed

    * **`DeleteMetricQuery` removed from `honeyhive.models`**
      * Internal query-params type that was exported but unused — no public method accepted or returned it. The public `client.metrics.delete(id=...)` signature is unchanged.
  </div>
</Update>