本页还没有译文
本页 61 段还没译成简体中文，下面显示的是英文原文。Versions & Compatibility
还没翻译译自英文（langfuse.com）本页 61 段都还没译
Reference for how Langfuse's server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments.
This part of the page is interactive; see it on the original page.
Langfuse v4 is generally available: self-hosted deployments upgrade with the v3 to v4 migration guide, and 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.
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 versions
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, including security patches. |
| Deprecated | Still works but is superseded; removal is noted in the matrix below. Migrate to the replacement. |
| End of life | Unsupported, no security patches. |
GA versions
| Component | GA version | Package / repo | Notes |
|---|---|---|---|
| Server | v4 | langfuse/langfuse  | Observations-first data model; self-hosted v3 receives security patches through January 31, 2027, then reaches end of life |
| Python SDK | v5 | langfuse  | OpenTelemetry-based since v3. Requires Python 3.11+ and Langfuse Cloud or self-hosted Langfuse v4.59.0+; see the v4 → v5 migration guide. |
| JS/TS SDK | v6 | @langfuse/*  | OpenTelemetry-based since v4. Requires Node.js 22+ and Langfuse Cloud or self-hosted Langfuse v4.59.0+; see the v5 → v6 migration guide. |
| Other languages | n/a | OpenTelemetry | Any OTel SDK to the Langfuse OTel endpoint |
Feature availability matrix
Langfuse Cloud runs v3 and v4 side by side until the v4 cutover on November 16, 2026 (2026-11-16). 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.
| Feature | Langfuse Cloud v3 (Deprecated as of Nov 16, 2026) | Langfuse Cloud v4 (GA) |
|---|---|---|
| Python · Upgrade guide | ||
| Python SDK v5 | Unsupported | Full |
| Python SDK v4 | Full | Full |
| Python SDK v3 | Full | Deprecated |
| Python SDK v2 | Full | Deprecated |
| Python SDK v1 | Unsupported | Unsupported |
| JS/TS · Upgrade guide | ||
| JS/TS SDK v6 | Unsupported | Full |
| JS/TS SDK v5 | Full | Full |
| JS/TS SDK v4 | Full | Deprecated |
| JS/TS SDK v3 / v2 | Full | Deprecated |
| JS/TS SDK v1 | Unsupported | Unsupported |
| Third-party instrumentation · OpenTelemetry docs | ||
OpenTelemetry/api/public/otel/v1/traces | Full | Full |
Direct scores ingestion/api/public/scores | Full | Full |
SDK scores ingestionscore-create via /api/public/ingestion | Full | Full |
Legacy trace and observation events/api/public/ingestion | Full | Deprecated |
| Read APIs · Public API docs | ||
Observations API v2 & Metrics API v2/api/public/v2/... | Full | Full |
Scores API v3/api/public/v3/scores | Full | Full |
Deprecated read APIstraces, observations, sessions, scores, metrics, dataset runs | Full | Deprecated |
| Integrations & exports · Export docs | ||
| Blob storage export | Traces & observations | Enriched observations |
| PostHog integration | Traces & observations | Enriched observations |
| Mixpanel integration | Traces & observations | Enriched observations |
| Legacy export source (traces and observations) | Full | Deprecated |
| Evaluations · LLM-as-a-judge docs | ||
| Observation-level evaluators | Full | Full |
| Trace-level evaluators | Full | Deprecated |
Python SDK v5
GA. Requires Langfuse v4 (self-hosted: v4.59.0 or later). The SDK sends spans with the v4 ingestion header and uses only the v4 Public API (Observations API v2, Metrics API v2, Scores API v3, Experiments API). The deprecated read APIs are not included. See the Python v4 → v5 upgrade guide.
JS/TS SDK v6
GA. Requires Langfuse v4 (self-hosted: v4.59.0 or later). The SDK sends spans with the v4 ingestion header and uses only the v4 Public API (Observations API v2, Metrics API v2, Scores API v3, Experiments API). The deprecated read APIs are not included. See the JS/TS v5 → v6 upgrade guide.
Python SDK v3
Deprecated. Upgrade to Python SDK v4.
Limitations:
| Capability | Langfuse Cloud v3 | Langfuse Cloud v4 |
|---|---|---|
| Tracing (OpenTelemetry) | Supported | Supported (data delayed up to 15 min; Python SDK v4 ≥ 4.7.0 for real time) |
| Datasets & experiments | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) |
Public API & querying (api.*) | Supported | Supported until the v4 cutover on November 16, 2026 (2026-11-16); then the deprecated read APIs are sunset |
Python SDK v2
Deprecated. Upgrade via the SDK upgrade paths.
Limitations:
| Capability | Langfuse Cloud v3 | Langfuse Cloud v4 |
|---|---|---|
| Tracing (legacy batch ingestion) | Supported | Removed on November 16, 2026 (2026-11-16); trace ingestion then stops working |
| Score ingestion | Supported | Supported |
| Datasets & experiments | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) |
Public API & querying (api.*) | Supported | Supported until November 16, 2026 (2026-11-16); then the deprecated read APIs are sunset |
JS/TS SDK v4
Deprecated. Upgrade to JS/TS SDK v5.
Limitations:
| Capability | Langfuse Cloud v3 | Langfuse Cloud v4 |
|---|---|---|
| Tracing (OpenTelemetry) | Supported | Supported (data delayed up to 15 min; JS/TS SDK v5 ≥ 5.4.0 for real time) |
| 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 November 16, 2026 (2026-11-16); then the deprecated read APIs are removed |
JS/TS SDK v3 / v2
Deprecated. Upgrade via the SDK upgrade paths.
Limitations:
| Capability | Langfuse Cloud v3 | Langfuse Cloud v4 |
|---|---|---|
| Tracing (legacy batch ingestion) | Supported | Removed on November 16, 2026 (2026-11-16); 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 November 16, 2026 (2026-11-16); then the deprecated read APIs are sunset |
OpenTelemetry
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 15 minutes. (Langfuse SDKs at Python ≥ 4.7.0 / JS ≥ 5.4.0 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.
Legacy trace and observation events
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 16, 2026 (2026-11-16), on self-hosted Langfuse v4 in events_only mode they are rejected. The same applies to the older POST /api/public/traces, /spans, /generations, and /events endpoints. Migrate to OpenTelemetry ingestion.
Observations API v2 & Metrics API v2
GA. Requires Langfuse v4. See the Observations API v2 and Metrics API v2 docs.
- Via SDK: these are the default resources (
api.observations,api.metrics) in Python SDK v4+ and JS/TS SDK v5+. On OSS v3, the defaults fail; with Python SDK v4 / JS/TS SDK v5, useapi.legacy.observations_v1/api.legacy.metrics_v1(Python) orapi.legacy.observationsV1/api.legacy.metricsV1(JS/TS). - Via REST:
GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime}andGET /api/public/v2/metrics?query={json}. - Data freshness: data from older SDKs (Python < 4.7.0, JS < 5.4.0) or OTel exporters without the
x-langfuse-ingestion-version: 4header 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 read APIs
Deprecated. Removed on Langfuse v4 and on Langfuse Cloud on November 16, 2026 (2026-11-16). The migration guide is the canonical per-endpoint mapping with parameter tables and before/after examples; it also documents the deprecated endpoints themselves.
Deprecated GET endpoints | Replacement |
|---|---|
/api/public/observations, /api/public/observations/{id} | Observations API v2 |
/api/public/traces, /api/public/traces/{id} | Observations API v2, filtered by traceId |
/api/public/sessions, /api/public/sessions/{id} | Observations API v2, filtered by sessionId |
/api/public/scores, /api/public/v2/scores (+ /{id}) | Scores API v3 |
/api/public/metrics, /api/public/metrics/daily | Metrics API v2 |
/api/public/datasets/{name}/runs (+ /{runName}) | Experiments API |
/api/public/dataset-run-items | Experiment Items API |
Trace-level evaluators
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 16, 2026 (2026-11-16). On self-hosted Langfuse v4 in events_only mode, they will no longer produce results.
Legacy export source (traces and observations)
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 16, 2026 (2026-11-16).
Frequently asked questions
I'm on Langfuse Cloud, which versions do I need to care about?
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 v5, JS/TS v6) and migrate away from deprecated endpoints before the v4 cutover on November 16, 2026 (2026-11-16).
I self-host Langfuse v3 and upgraded to Python SDK v4 / JS SDK v5, what works?
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. Python SDK v5 and JS/TS SDK v6 require Langfuse v4, so stay on Python SDK v4 / JS SDK v5 until you upgrade your server. The self-hosted compatibility matrix has the full picture per server version.
My data takes minutes to show up in the UI, why?
On the v4 data model, data from Python SDK < 4.7.0, JS SDK < 5.4.0, or OTel exporters without the x-langfuse-ingestion-version: 4 header can be delayed by up to 15 minutes. Upgrade to Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0 (or set the header) for real-time data.
When do old SDKs stop working on Langfuse Cloud?
Python SDK v2 and JS/TS SDK v3 (and older) send traces via the legacy batch ingestion API, which is removed on Langfuse Cloud as of November 16, 2026 (2026-11-16). Upgrade to the GA SDK majors now; see the SDK upgrade paths.
Does upgrading my self-hosted server break my SDKs?
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). After upgrading to v4, you can also upgrade to Python SDK v5 and JS SDK v6, which require Langfuse v4. Check the self-hosted compatibility matrix before upgrading.