Versions & compatibility
Reference for how Langfuse's server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments.
Langfuse Cloud runs the latest version, including both GA and preview features. New capabilities usually ship to Langfuse Cloud first (as preview), then become GA for OSS / self-hosted once validated. Availability therefore differs between the two. This page calls out the difference per version, API, and endpoint.
GA versions
Generally available versions. Forward-looking tracks that are not yet GA, such as the server v4 Fast Preview, are in preview.
| Component | GA version | Package / repo | Notes |
|---|---|---|---|
| Server | v3 | langfuse/langfuse  | ClickHouse + Redis + S3/blob storage + worker |
| Python SDK | v4 | langfuse  | OpenTelemetry-based since v3. Requires Python 3.9+. |
| JS/TS SDK | v5 | @langfuse/*  | OpenTelemetry-based since v4. Requires Node.js 20+. |
| Other languages | n/a | OpenTelemetry | Any OTel SDK to the Langfuse OTel endpoint |
SDK ↔ server compatibility
Recent SDKs require a recent self-hosted server. Cloud always satisfies these minimums.
| SDK & version | Min. self-hosted server | Status | Upgrade guide |
|---|---|---|---|
| Python SDK v4 | ≥ 3.125.0 | GA | |
| Python SDK v3 | ≥ 3.125.0 | Legacy | Python v3 → v4 |
| Python SDK v2 | server v2+ | Legacy | Python v2 → v3 |
| Python SDK v1 | unsupported on v3 | End of life | All paths |
| JS/TS SDK v5 | ≥ 3.95.0 | GA | |
| JS/TS SDK v4 | ≥ 3.95.0 | Legacy | JS v4 → v5 |
| JS/TS SDK v3 / v2 | server v2+ | Legacy | JS v3 → v4 |
| JS/TS SDK v1 | unsupported on v3 | End of life | All paths |
The server is backwards compatible with older SDKs. When upgrading an SDK, run a recent server too. See the versioning policy.
Server versions
| Version | Highlights | Status | Security patches | Upgrade guide |
|---|---|---|---|---|
| v1 | PostgreSQL, synchronous ingestion. | End of life | No | v1 → v2 |
| v2 | PostgreSQL, synchronous ingestion. Rebuilt usage & cost tracking. Supports SDK v1+. | End of life | No | v2 → v3 |
| v3 | ClickHouse + Redis + S3/blob storage + worker; asynchronous, event-driven. Requires SDK v2+. | GA | Yes | |
| v4 (Fast Preview) | Observations-first data model, faster at scale. GA on Cloud; self-hosted via env opt-in (migration in progress). | Preview | Yes | Adopt |
v1 and v2 are end of life; upgrade is recommended. v2 → v3 is an infrastructure migration (adds ClickHouse, Redis, blob storage). Self-hosted v3 requires PostgreSQL ≥ 12, ClickHouse ≥ 24.3, and Redis/Valkey ≥ 7 (maxmemory-policy=noeviction).
API versions
Ingestion
| Endpoint | Status | Notes |
|---|---|---|
POST /api/public/otel/v1/traces | Recommended | OpenTelemetry (OTLP) endpoint, server v3+ (self-hosted ≥ 3.22.0). The path forward for all ingestion. |
POST /api/public/ingestion | Deprecated | Legacy batch ingestion; async on v3+ (returns 207). Use the OTel endpoint. |
Read APIs
Current versions use cursor pagination and selective field groups. Legacy endpoints still work but are superseded by a current version. Deprecated endpoints will be removed in a future version; migrate to the replacement shown in Notes.
| Endpoint | Status | Notes |
|---|---|---|
GET /api/public/v2/observations | Current | Cloud (GA); self-hosted via the v4 preview opt-in |
GET /api/public/observations | Legacy | |
GET /api/public/observations/{id} | Legacy | Superseded by GET /api/public/v2/observations |
GET /api/public/v2/metrics | Current | Cloud (GA); self-hosted via the v4 preview opt-in |
GET /api/public/metrics | Legacy | |
GET /api/public/v3/scores | Current | GA (Cloud and self-hosted) |
GET /api/public/scores | Legacy | |
GET /api/public/v2/scores | Deprecated | Use GET /api/public/v3/scores |
GET /api/public/traces/{id} | Current | Single trace with nested observations and scores |
GET /api/public/sessions | Legacy | Not recommended for extraction; use GET /api/public/v2/observations with a sessionId filter |
GET /api/public/sessions/{sessionId} | Legacy | Single session with traces; use GET /api/public/v2/observations with a sessionId filter |
/api/public/mcp | Current | MCP server; its observations and metrics tools follow the v2 preview availability above |
- Self-hosted Observations/Metrics v2 require the v4 preview opt-in (
LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN). - SDKs default to the current resources (
api.observations,api.scores,api.metrics); legacy versions are underapi.legacy.*(e.g.api.legacy.observations_v1/observationsV1). On self-hosted, use the legacy observations and metrics resources until their v2 APIs are GA there. - Metrics v2 has no
tracesview.
Real-time v2 data requires Python SDK ≥ 4.0.0, JS/TS SDK ≥ 5.0.0, or x-langfuse-ingestion-version: 4 on your OTEL exporter. Otherwise data can lag up to 10 minutes.
See the Observations API and Metrics API pages for details.
Evaluations & integrations
Each has a current version (built on the v4 data model) and a legacy version that still works and may be deprecated later. Some capabilities also require a specific plan or edition; see Cloud pricing and self-hosting pricing.
| Capability | Current | Legacy |
|---|---|---|
| Evaluation | Span / observation-level (server ≥ 3.153.0; Python SDK v3+ / JS SDK v4+) | Trace-level (Python SDK v2+ / JS SDK v3+) |
| Dataset evaluation | Experiment-level | Dataset-run-level |
| PostHog | Enriched observations | Traces and observations |
| Blob storage export | Enriched observations | Traces and observations |
| Mixpanel | Enriched observations | Traces and observations |
- The enriched (current) analytics exports build on the v4 data model; on self-hosted they require the v4 preview opt-in (Cloud is unaffected).
- On Cloud, projects created on or after 2026-05-20 can no longer select the legacy export source (existing projects and self-hosted are unaffected).
How versioning works
Langfuse uses semantic versioning: a major bump means a breaking change (infrastructure or public-API removal). Server and SDKs are versioned independently. Release notes: server, Python SDK, JS/TS SDK.
Last edited
