Legacy APIs and ingestion removed (date will follow)
Langfuse v4 is generally available: Langfuse Cloud, where v4 has been rolling out in preview since March 2026, will switch to v4 as the only experience, at which point remaining legacy APIs and ingestion paths are also removed. Self-hosted release is on the way, exact dates will follow.
The compatibility rule: each Langfuse server major version aims to support the current and the previous SDK major version of each language. New SDK versions require a recent server version, as some features may not be available on older servers; see the feature availability matrix.
We try very hard to uphold this rule. v4 breaks backwards compatibility with older SDKs; see the Langfuse v4 page for all information.
Deployment
How versioning works
Langfuse Cloud
Always runs the latest Langfuse version; server versions are managed for you. Only your SDK version and the API endpoints you call matter; the self-hosted server minimums on this page do not apply. Breaking removals happen on published dates.
Self-hosted (OSS & Enterprise)
You choose when to upgrade the server. 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. SDK majors require the minimum server versions in the self-hosted compatibility matrix; breaking removals only happen in major server releases (see the versioning policy and upgrade documentation).
Langfuse Cloud runs v3 and v4 side by side until the v4 cutover (dates will follow). The v3 column is deprecated: everything marked Deprecated below keeps working until the cutover and is then removed. Click a row for details.
Self-hosting Langfuse? Use the self-hosted compatibility matrix instead; it covers each server version and the minimum server version per SDK.
Removed at the v4 cutover (date will follow); trace ingestion then stops working
Score ingestion
Supported
Supported
Datasets & experiments
Datasets only (experiments require JS/TS SDK v5)
Datasets only (experiments require JS/TS SDK v5)
Public API & querying (api.*)
Supported
Supported until the v4 cutover (date will follow); then the deprecated read APIs are removed
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. The same applies to the older POST /api/public/traces, /spans, /generations, and /events endpoints. Migrate to OpenTelemetry ingestion.
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 older SDKs (Python < 4.0.0, JS < 5.0.0) or OTel exporters without the x-langfuse-ingestion-version: 4 header can appear on these APIs with up to a 10-minute delay. Upgrade to Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0 (or set the header) for real-time data.
Deprecated. Removed on Langfuse v4 (Langfuse Cloud: removal date will follow). The migration guide is the canonical per-endpoint mapping with parameter tables and before/after examples; it also documents the deprecated endpoints themselves.
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).
Only your SDK version and the API endpoints you call. Langfuse Cloud always runs the latest server version, so self-hosted server minimums never apply to you. Keep your SDKs on the GA major version (Python v4, JS/TS v5) and migrate away from deprecated endpoints before the v4 cutover (dates will follow).
Tracing, prompt management, datasets, and scores work fully (server ≥ 3.63.0). The default api.observations and api.metrics resources call v2 endpoints that require Langfuse v4; use the api.legacy.* resources until you upgrade your server to v4. The self-hosted compatibility matrix has the full picture per server version.
On the v4 data model, data from Python SDK < 4.0.0, JS SDK < 5.0.0, or OTel exporters without the x-langfuse-ingestion-version: 4 header can be delayed by up to 10 minutes. Upgrade to Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0 (or set the header) for real-time data.
Python SDK v2 and JS/TS SDK v3 (and older) send traces via the legacy batch ingestion API, which is removed on Langfuse Cloud at the v4 cutover (date will follow). Upgrade to the GA SDK majors now; see the SDK upgrade paths.
Each server major supports the current and previous SDK major of each language. Upgrading v3 → v4 keeps Python SDK v3+/v4 and JS SDK v4/v5 working (older SDKs lose real-time visibility; Python v2 / JS v3 trace ingestion is not supported on v4). Check the self-hosted compatibility matrix before upgrading.
