---
title: Versions & Compatibility
description: How Langfuse server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments, including the SDK ↔ server compatibility matrix.
---
# Versions & Compatibility
Reference for how Langfuse's server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments.
- [Langfuse Cloud](/docs/v4): v3 and the v4 preview run side by side until November 16, 2026. From then, Langfuse Cloud is v4-only and legacy APIs, features, and ingestion are removed.
- [Self-hosted Langfuse](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4): v4 has been generally available since July 29, 2026. Langfuse v3 receives security patches through January 2027.
[Langfuse v4](/docs/v4) is generally available: self-hosted deployments upgrade with the [v3 to v4 migration guide](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4), 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](#sdk-server).
We try very hard to uphold this rule. v4 breaks backwards compatibility with older SDKs; see the [Langfuse v4 page](/docs/v4) 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](/self-hosting/upgrade/versioning#sdk-server); breaking removals only happen in major server releases (see the [versioning policy](/self-hosting/upgrade/versioning) and [upgrade documentation](/self-hosting/upgrade)). |
## Langfuse versions [#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. |
| **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 [#ga]
| Component | GA version | Package / repo | Notes |
| --------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Server | v4 | [langfuse/langfuse](https://github.com/langfuse/langfuse/releases) 
| [Observations-first data model](/docs/v4#what-changed); v3 continues to receive security patches |
| Python SDK | v4 | [`langfuse`](https://pypi.org/project/langfuse/) 
| OpenTelemetry-based since v3. Requires Python 3.9+. |
| JS/TS SDK | v5 | [`@langfuse/*`](https://www.npmjs.com/package/@langfuse/tracing) 
| OpenTelemetry-based since v4. Requires Node.js 20+. |
| Other languages | n/a | [OpenTelemetry](/integrations/native/opentelemetry) | Any OTel SDK to the Langfuse OTel endpoint |
## Feature availability matrix [#sdk-server]
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](/self-hosting/upgrade/versioning#sdk-server) 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](/docs/observability/sdk/upgrade-path) | | |
| Python SDK v4 | Full | Full |
| Python SDK v3 | Full | Deprecated |
| Python SDK v2 | Full | Deprecated |
| Python SDK v1 | Unsupported | Unsupported |
| **JS/TS** · [Upgrade guide](/docs/observability/sdk/upgrade-path) | | |
| 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](/integrations/native/opentelemetry) | | |
| OpenTelemetry
`/api/public/otel/v1/traces` | Full | Full |
| Direct scores ingestion
`/api/public/scores` | Full | Full |
| SDK scores ingestion
`score-create` via `/api/public/ingestion` | Full | Full |
| Legacy trace and observation events
`/api/public/ingestion` | Full | Deprecated |
| **Read APIs** · [Public API docs](/docs/api-and-data-platform/features/public-api) | | |
| Observations API v2 & Metrics API v2
`/api/public/v2/...` | Full | Full |
| Scores API v3
`/api/public/v3/scores` | Full | Full |
| Deprecated read APIs
`traces, observations, sessions, scores, metrics, dataset runs` | Full | Deprecated |
| **Integrations & exports** · [Export docs](/docs/api-and-data-platform/features/export-to-blob-storage) | | |
| [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Traces & observations | Enriched observations |
| [PostHog integration](/integrations/analytics/posthog) | Traces & observations | Enriched observations |
| [Mixpanel integration](/integrations/analytics/mixpanel) | Traces & observations | Enriched observations |
| Legacy export source (traces and observations) | Full | Deprecated |
| **Evaluations** · [LLM-as-a-judge docs](/docs/evaluation/evaluation-methods/llm-as-a-judge) | | |
| Observation-level evaluators | Full | Full |
| Trace-level evaluators | Full | Deprecated |
Deprecated. Upgrade to [Python SDK v4](/docs/observability/sdk/upgrade-path/python-v3-to-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 |
Deprecated. Upgrade via the [SDK upgrade paths](/docs/observability/sdk/upgrade-path).
**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 |
Deprecated. Upgrade to [JS/TS SDK v5](/docs/observability/sdk/upgrade-path/js-v4-to-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 |
Deprecated. Upgrade via the [SDK upgrade paths](/docs/observability/sdk/upgrade-path).
**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 |
GA. Any OpenTelemetry SDK can export to the OTLP endpoint, available since OSS [3.22.0](https://github.com/langfuse/langfuse/releases/tag/v3.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](/integrations/native/opentelemetry).
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](/faq/all/deprecated-api-migration#ingestion).
GA. Requires Langfuse v4. See the [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) and [Metrics API v2](/docs/metrics/features/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 older SDKs (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. 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 and on Langfuse Cloud on November 16, 2026 (2026-11-16). The [migration guide](/faq/all/deprecated-api-migration) is the canonical per-endpoint mapping with parameter tables and before/after examples; it also documents the [deprecated endpoints](/faq/all/deprecated-api-migration#endpoints) themselves.
| Deprecated `GET` endpoints | Replacement |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `/api/public/observations`, `/api/public/observations/{id}` | [Observations API v2](/faq/all/deprecated-api-migration#observations) |
| `/api/public/traces`, `/api/public/traces/{id}` | [Observations API v2, filtered by `traceId`](/faq/all/deprecated-api-migration#traces) |
| `/api/public/sessions`, `/api/public/sessions/{id}` | [Observations API v2, filtered by `sessionId`](/faq/all/deprecated-api-migration#sessions) |
| `/api/public/scores`, `/api/public/v2/scores` (+ `/{id}`) | [Scores API v3](/faq/all/deprecated-api-migration#scores) |
| `/api/public/metrics`, `/api/public/metrics/daily` | [Metrics API v2](/faq/all/deprecated-api-migration#metrics) |
| `/api/public/datasets/{name}/runs` (+ `/{runName}`) | [Experiments API](/faq/all/deprecated-api-migration#dataset-runs) |
| `/api/public/dataset-run-items` | [Experiment Items API](/faq/all/deprecated-api-migration#dataset-runs) |
Deprecated. Migrate to [observation-level evaluators](/faq/all/llm-as-a-judge-migration). 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.
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 [#faq]
### I'm on Langfuse Cloud, which versions do I need to care about? [#faq-cloud]
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 on November 16, 2026 (2026-11-16).
### I self-host Langfuse v3 and upgraded to Python SDK v4 / JS SDK v5, what works? [#faq-new-sdk-old-server]
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](/self-hosting/upgrade/versioning#sdk-server) has the full picture per server version.
### My data takes minutes to show up in the UI, why? [#faq-delay]
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? [#faq-cloud-cutover]
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](/docs/observability/sdk/upgrade-path).
### Does upgrading my self-hosted server break my SDKs? [#faq-server-upgrade]
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](/self-hosting/upgrade/versioning#sdk-server) before upgrading.
---
## Agent Instructions
This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/compatibility.md`.
### Querying these docs
If the answer is not on this page, query the documentation instead of guessing:
- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:
```bash
curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
```
- **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).
### Before writing Langfuse code
- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal.
Found an error in these docs? Please open an issue at .