Langfuse v4

Langfuse v4 rebuilds the data model around observations: trace-level attributes live on every observation, which removes expensive joins and makes 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

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. Upgrade to Python SDK v4 or JS/TS SDK v5 (the guides cover each major-version hop).
2. Replace update_current_trace() / updateActiveTrace() with propagate_attributes(); it pushes user_id, session_id, tags, and metadata to all child observations.
3. Verify in the in-app migration view that no required actions remain.

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

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

1. 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.
2. Replace update_current_trace() / updateActiveTrace() with propagate_attributes() (Python guide, JS guide).
3. Move reads from the v1 endpoints (api.legacy.*, or the api.observations / api.metrics defaults of SDK v3/v4) to the Observations API v2 and Metrics API v2.
4. Migrate trace-level LLM-as-a-judge evaluators to the observation level.

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. 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. Migrate trace-level evaluators and legacy export sources, if you use them (see what changed).
3. Upgrade the server from v3 to v4 following the upgrade documentation.
4. After the server upgrade, switch API reads from api.legacy.* to the default api.observations / api.metrics; the v2 endpoints are now served by your deployment.

Direct API and OpenTelemetry users

Deadline: November 30, 2026 for the v1 read APIs on Langfuse Cloud.

1. OpenTelemetry: 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 (setup guide).
2. REST: move v1 reads to GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime}, GET /api/public/v2/metrics?query={json}, and GET /api/public/v3/scores. The full endpoint list with replacements is in the compatibility matrix.
3. Exports: switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations". Remaining legacy exports are switched automatically on November 30, 2026.

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.

---

---