Versioning is key to ensure compatibility between Langfuse Server, SDKs, and custom integrations via the Public API. Thus, we take semantic versioning seriously.
Langfuse Server and SDKs are versioned independently to allow for more flexibility in upgrading components. The compatibility rule: each server major version aims to support the current and the previous SDK major version of each language, and each SDK major requires a minimum server version. We try extremely hard to uphold this rule, but the v4 transition is an exception: it ends support for older SDK majors on a published schedule (see the feature availability matrix).
Server: Can be upgraded independently of SDK versions within the supported range. Major server upgrades can drop support for old SDK majors; check the feature availability matrix and the upgrade guide before upgrading.
SDKs: Older SDK majors keep working on newer servers until they are deprecated and removed. New SDK majors require the minimum server versions listed in the feature availability matrix.
We recommend keeping the Langfuse Server up to date to ensure access to all features and security updates.
Langfuse Cloud deploys continuously and always runs the latest Langfuse version. New capabilities are battle-tested on Langfuse Cloud before they ship in a self-hosted release, so Cloud can run ahead of the latest self-hosted version, and some features may be enabled on Cloud before they are available self-hosted.
Consequences:
On Cloud, server versions are managed for you; only SDK versions and API endpoints matter.
Breaking removals on Cloud are announced with a migration window and happen on published dates; on self-hosted they only happen in major releases. Cloud removals are tracked in the Langfuse Cloud matrix, self-hosted support in the matrix below.
The matrix below shows what each self-hosted server major version supports: SDK majors with their minimum server versions, ingestion paths, read APIs, exports, and evaluators. Click a row for details and replacement endpoints.
On Langfuse Cloud, server versions are managed for you; use the Langfuse Cloud matrix instead.
GA. Requires self-hosted server ≥ 3.125.0; OSS v2 and older are unsupported.
Limitations:
Capability
OSS v3
OSS v4
Tracing (OpenTelemetry)
Supported
Supported (real time with SDK ≥ 4.7.0)
Public API & querying (api.*)
Use the legacy APIsapi.legacy.observations_v1 / api.legacy.metrics_v1
Supported (v1 APIs are deprecated (removal date will follow))
Deprecated. Requires self-hosted server ≥ 3.125.0; OSS v2 and older are unsupported.
Limitations:
Capability
OSS v3
OSS v4
Tracing (OpenTelemetry)
Supported
Supported (data delayed up to 10 min)
Datasets & experiments
Datasets only (experiments require Python SDK v4)
Datasets only (experiments require Python SDK v4)
Public API & querying (api.*)
Supported
v1 APIs are deprecated (removal date will follow)
Deprecated.
Limitations:
Capability
OSS v2
OSS v3
OSS v4
Tracing (legacy batch ingestion)
Supported
Supported
Unsupported
Datasets & experiments
Datasets only (experiments require Python SDK v4)
Datasets only (experiments require Python SDK v4)
Datasets only (experiments require Python SDK v4)
Media (multimodal)
Requires OSS v3
Supported
Supported
Public API & querying (api.*)
Supported
Supported
v1 APIs are deprecated (removal date will follow)
GA. Requires self-hosted server ≥ 3.95.0; OSS v2 and older are unsupported.
Limitations:
Capability
OSS v3
OSS v4
Tracing (OpenTelemetry)
Supported
Supported (real time with SDK ≥ 5.4.0)
Public API & querying (api.*)
Use the legacy APIsapi.legacy.observationsV1 / api.legacy.metricsV1
Supported (v1 APIs are deprecated (removal date will follow))
Deprecated. Requires self-hosted server ≥ 3.95.0; OSS v2 and older are unsupported.
Limitations:
Capability
OSS v3
OSS v4
Tracing (OpenTelemetry)
Supported
Supported (data delayed up to 10 min)
Datasets & experiments
Datasets only (experiments require JS/TS SDK v5)
Datasets only (experiments require JS/TS SDK v5)
Public API & querying (api.*)
Supported
v1 APIs are deprecated (removal date will follow)
Deprecated.
Limitations:
Capability
OSS v2
OSS v3
OSS v4
Tracing (legacy batch ingestion)
Supported
Supported
Unsupported
Datasets & experiments
Datasets only (experiments require JS/TS SDK v5)
Datasets only (experiments require JS/TS SDK v5)
Datasets only (experiments require JS/TS SDK v5)
Media (multimodal)
Requires OSS v3
Supported
Supported
Public API & querying (api.*)
Supported
Supported
v1 APIs are deprecated (removal date will follow)
GA. Any OpenTelemetry SDK can export to the OTLP endpoint, available since OSS 3.22.0. On Langfuse v4, send the x-langfuse-ingestion-version: 4 header on your span exporter to see data in real time; without it, data can be delayed by up to 10 minutes. (Langfuse SDKs qualify for real time automatically; self-hosted deployments can set LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct to make all OTLP ingestion real time without the header.) See the OpenTelemetry setup guide.
Deprecated. Trace, span, and generation events via the legacy batch ingestion API are not supported on the v4 data model: on Langfuse Cloud they keep working until the v4 cutover (date will follow), on self-hosted Langfuse v4 they are rejected.
Deprecated. Removed on Langfuse v4 (Langfuse Cloud: removal date will follow). The full list and replacements:
Via SDK: these are the default resources in Python SDK v4 (api.observations, api.metrics) and JS/TS SDK v5 (api.observations, api.metrics). On OSS v3, the defaults fail; use api.legacy.observations_v1 / api.legacy.metrics_v1 (Python) or api.legacy.observationsV1 / api.legacy.metricsV1 (JS/TS).
Via REST:GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime} and GET /api/public/v2/metrics?query={json}.
Data freshness: data from SDKs below Python 4.7.0 / JS 5.4.0, or OTel exporters without the x-langfuse-ingestion-version: 4 header, can appear on these APIs with up to a 10-minute delay.
Deprecated. Migrate to observation-level evaluators. Trace-level evaluators are not supported on the v4 data model; on Langfuse Cloud they keep running until the v4 cutover (date will follow).
Deprecated. Exports built on the legacy "traces and observations" source are replaced by the enriched observations source (v4 data model). On Langfuse Cloud, projects created on or after 2026-05-20 cannot select legacy sources, new legacy export integrations cannot be created since 2026-06-22, and remaining legacy exports are switched to the enriched source automatically at the Cloud v4 cutover (date will follow).
