Reference for how Langfuse's server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments.
Jan 2026Apr 2026Jul 2026Oct 2026Jan 2027Apr 2027
Langfuse v4 is generally available: the self-hosted release ships by August 1, 2026, and Langfuse Cloud, where v4 has been rolling out in preview since March 2026, switches to v4 as the only experience at the end of October 2026. Remaining legacy APIs and ingestion paths are removed on November 30, 2026.
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 below; breaking removals only happen in major server releases (see the versioning policy and upgrade documentation). |
Every Langfuse component (server, SDKs, and APIs) moves through these lifecycle stages:
| Stage | Meaning |
|---|
| Preview | New capabilities that are production-ready, but interfaces or API design may still change. |
| GA | Recommended and fully supported. |
| Deprecated | Still works but is superseded; it will be removed on the dates noted in the matrix below. Migrate to the replacement. |
| End of life | Unsupported, no security patches. |
| Client | OSS v2 (End of life) | OSS v3 (Deprecated) | OSS v4 (GA) | Status |
|---|
| Python · Upgrade guide | | | | |
| Python SDK v4 | Unsupported | ≥ 3.125.0 | Full | GA |
| Python SDK v3 | Unsupported | ≥ 3.125.0 | Deprecated | Deprecated |
| Python SDK v2 | Full | Full | Deprecated | Deprecated |
| Python SDK v1 | Full | Unsupported | Unsupported | End of life |
| JS/TS · Upgrade guide | | | | |
| JS/TS SDK v5 | Unsupported | ≥ 3.95.0 | Full | GA |
| JS/TS SDK v4 | Unsupported | ≥ 3.95.0 | Deprecated | Deprecated |
| JS/TS SDK v3 / v2 | Full | Full | Deprecated | Deprecated |
| JS/TS SDK v1 | Full | Unsupported | Unsupported | End of life |
| Third-party instrumentation · OpenTelemetry docs | | | | |
OpenTelemetry
/api/public/otel/v1/traces | Unsupported | ≥ 3.22.0 | Full | GA |
Scores ingestion
/api/public/scores | Full | Full | Full | GA |
Legacy ingestion API
/api/public/ingestion | Full | Full | Deprecated | Deprecated |
| Read APIs · Public API docs | | | | |
Observations API v2 & Metrics API v2
/api/public/v2/... | Unsupported | Unsupported | Full | GA |
Scores API v3
/api/public/v3/scores | Unsupported | Full | Full | GA |
v1 read APIs
/api/public/... | Full | Full | Deprecated | Deprecated |
| Integrations & exports · Export docs | | | | |
| Blob storage export | Unsupported | Traces & observations | Enriched observations | GA |
| PostHog integration | Unsupported | Traces & observations | Enriched observations | GA |
| Mixpanel integration | Unsupported | Traces & observations | Enriched observations | GA |
| Legacy export source (traces and observations) | Unsupported | Full | Deprecated | Deprecated |
| Evaluations · LLM-as-a-judge docs | | | | |
| Observation-level evaluators | Unsupported | ≥ 3.153.0 | Full | GA |
| Trace-level evaluators | Full | Full | Deprecated | Deprecated |
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 APIs api.legacy.observations_v1 / api.legacy.metrics_v1 | Supported (v1 APIs are deprecated until Nov 30, 2026) |
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 until Nov 30, 2026 |
Deprecated.
Limitations:
| Capability | OSS v2 | OSS v3 | OSS v4 |
|---|
| Tracing (legacy batch ingestion) | Supported | Supported | Stops Nov 30, 2026 |
| 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 until Nov 30, 2026 |
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 APIs api.legacy.observationsV1 / api.legacy.metricsV1 | Supported (v1 APIs are deprecated until Nov 30, 2026) |
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 until Nov 30, 2026 |
Deprecated.
Limitations:
| Capability | OSS v2 | OSS v3 | OSS v4 |
|---|
| Tracing (legacy batch ingestion) | Supported | Supported | Stops Nov 30, 2026 |
| 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 until Nov 30, 2026 |
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 November 30, 2026, on self-hosted Langfuse v4 they are rejected.
Deprecated. Removed on Langfuse v4 (Langfuse Cloud: November 30, 2026). The full list and replacements:
Deprecated GET endpoints | Replacement |
|---|
/api/public/observations
/api/public/observations/{id} | GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime} |
/api/public/traces
/api/public/traces/{id} | GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime}
add &traceId={id} for a single trace |
/api/public/sessions
/api/public/sessions/{id} | GET /api/public/v2/observations?sessionId={id}&fromStartTime={datetime}&toStartTime={datetime} |
/api/public/scores
/api/public/scores/{id}
/api/public/v2/scores
/api/public/v2/scores/{id} | GET /api/public/v3/scores |
/api/public/metrics
/api/public/metrics/daily | GET /api/public/v2/metrics?query={json} |
GA. Requires Langfuse v4. See the Observations API v2 and Metrics API v2 docs.
- 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 November 30, 2026.
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 on November 30, 2026.
Only your SDK version and the API endpoints you call. Langfuse Cloud always runs the latest server version, so the self-hosted minimums on this page 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 dates noted in the matrix above.
Tracing, prompt management, datasets, and scores work fully (server ≥ 3.125.0 for Python, ≥ 3.95.0 for JS/TS). 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.
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 on November 30, 2026. Upgrade to the GA SDK majors before then; 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 matrix above before upgrading.
