Langfuse v4

Langfuse v4 rebuilds the data model around observations: trace-level attributes live on every observation, and records are immutable (written once, never updated). This removes expensive joins and the deduplication of updated records at read time, making queries an order of magnitude faster at scale. This page is the starting point for upgrading. Find your situation below, follow the steps, and check the Versions & Compatibility page for the full matrix.

Timeline

On Langfuse Cloud, review your project's remaining migration actions directly in the app.

What you need to do

Not sure which combinations are supported? The compatibility matrix shows every SDK, API, and export against each server version.

Langfuse Cloud with older SDKs (Python v2 / JS v3 or older)

Deadline: November 30, 2026. These SDKs send traces via the legacy ingestion API, which is removed on that date; trace ingestion stops working. Score ingestion is unaffected.

1. Ingestion: upgrade to Python SDK v4 or JS/TS SDK v5 (the guides cover each major-version hop), and replace update_current_trace() / updateActiveTrace() with propagate_attributes().
2. Read APIs: move reads from the v1 endpoints (api.legacy.* or direct REST calls) to the Observations API v2 and Metrics API v2. The full endpoint list with replacements is in the compatibility matrix.
3. Evaluators: migrate trace-level LLM-as-a-judge evaluators to the observation level.
4. Exports: switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations".
5. UI: if your organization was created before April 14, 2026, enable the Preview toggle (bottom-left in the UI) to use the v4 experience; newer organizations already run it.
6. Verify: check the in-app migration view until no required actions remain.

Langfuse Cloud with current SDKs (Python v3+ / JS v4+)

Deadline: November 30, 2026 for the v1 read APIs, trace-level evaluators, and legacy exports; the SDK upgrade itself is recommended before the end of October 2026 so your data stays real time.

1. Ingestion: upgrade to Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0 (below these versions, data appears with up to a 10-minute delay on the v4 data model) and replace update_current_trace() / updateActiveTrace() with propagate_attributes() (Python guide, JS guide).
2. Read APIs: move reads from the v1 endpoints (api.legacy.* or direct REST calls) to the Observations API v2 and Metrics API v2. The full endpoint list with replacements is in the compatibility matrix.
3. Evaluators: migrate trace-level LLM-as-a-judge evaluators to the observation level.
4. Exports: switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations".
5. UI: if your organization was created before April 14, 2026, enable the Preview toggle (bottom-left in the UI) to use the v4 experience; newer organizations already run it.
6. Verify: check the in-app migration view until no required actions remain.

Self-hosted deployments

No forced deadline. v4 ships by August 1, 2026; v3 continues to receive security patches. Upgrade at your own pace, in this order:

1. Ingestion: upgrade SDKs first: Python SDK v4 / JS/TS SDK v5. Python SDK v2 and JS SDK v3 cannot send traces to a v4 server.
2. Evaluators: migrate trace-level LLM-as-a-judge evaluators to the observation level.
3. Exports: switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations".
4. Server: upgrade from v3 to v4 following the upgrade documentation. The v4 UI ships with the server; no toggle is needed.
5. Read APIs: move reads from the v1 endpoints (api.legacy.* or direct REST calls) to the Observations API v2 and Metrics API v2. The full endpoint list with replacements is in the compatibility matrix.

Direct API and OpenTelemetry users

Deadline: November 30, 2026 for legacy trace ingestion and the v1 read APIs on Langfuse Cloud.

1. Ingestion: everyone still sending trace, span, or generation events to the legacy POST /api/public/ingestion API must move to the OpenTelemetry endpoint POST /api/public/otel/v1/traces. Set the x-langfuse-ingestion-version: 4 header on your span exporter for real-time data, and propagate trace attributes (user_id, session_id, ...) to all spans.
2. Read APIs: move reads from the v1 endpoints (api.legacy.* or direct REST calls) to the Observations API v2 and Metrics API v2. The full endpoint list with replacements is in the compatibility matrix.
3. Evaluators: migrate trace-level LLM-as-a-judge evaluators to the observation level.
4. Exports: switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations".

What changed

Why observations-first: agentic applications produce traces with hundreds of operations, and the operations engineers care about were hidden inside one trace row. With observations as the primary entity you query the operations directly ("which LLM calls are slow?"), charts load faster over large time ranges, and observation-level evaluations run in seconds. The data model docs explain the model; the observations guide covers day-to-day workflows in the UI.

Questions

Ask rollout and migration questions in the dedicated GitHub Discussion; we use that thread for updates and answers.

---

---