Upgrade to Langfuse v4
Langfuse v4 rebuilds the data model around observations; the Langfuse v4 page explains what changed and why. Find your situation below and follow the steps.
Upgrading your SDKs is the most important step; everything else builds on it. Not sure which combinations are supported? The compatibility matrix shows every SDK, API, and export on Langfuse Cloud; self-hosters use the self-hosted matrix.
Langfuse Cloud with older SDKs (Python v2 / JS v3 or older)
Deadline: will be announced. These SDKs send traces via the legacy ingestion API, which is removed when Langfuse Cloud switches to v4; trace ingestion then stops working. Score ingestion is unaffected.
Ingestion
Upgrade to the latest SDK majors, Python v4 and JS/TS v5; the SDK upgrade paths cover each major-version hop. Then replace update_current_trace() / updateActiveTrace() with propagate_attributes().
Read APIs
Move reads from the deprecated endpoints (api.legacy.* or direct REST calls) to the Observations API v2 and Metrics API v2. The migration guide has the per-endpoint replacements, parameter mappings, and before/after examples.
Evaluators
Migrate trace-level LLM-as-a-judge evaluators to the observation level. If you upgrade your SDKs before migrating, keep supplying trace input/output via the deprecated trace I/O methods (set_current_trace_io() in Python, setActiveTraceIO() in JS/TS) so your existing trace-level evaluators keep receiving data until the new ones are validated.
Exports
Switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations".
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.
Verify
Check the in-app migration view until no required actions remain.
Langfuse Cloud with current SDKs (Python v3+ / JS v4+)
Deadline: will be announced for the deprecated read APIs, trace-level evaluators, and legacy exports; upgrade your SDKs now so your data stays real time.
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).
Read APIs
Move reads from the deprecated endpoints (api.legacy.* or direct REST calls) to the Observations API v2 and Metrics API v2. The migration guide has the per-endpoint replacements, parameter mappings, and before/after examples.
Evaluators
Migrate trace-level LLM-as-a-judge evaluators to the observation level. If you upgrade your SDKs before migrating, keep supplying trace input/output via the deprecated trace I/O methods (set_current_trace_io() in Python, setActiveTraceIO() in JS/TS) so your existing trace-level evaluators keep receiving data until the new ones are validated.
Exports
Switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations".
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.
Verify
Check the in-app migration view until no required actions remain.
Direct API and OpenTelemetry users
Deadline: will be announced for legacy trace ingestion and the deprecated read APIs on Langfuse Cloud.
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.
Read APIs
Move reads from the deprecated endpoints (api.legacy.* or direct REST calls) to the Observations API v2 and Metrics API v2. The migration guide has the per-endpoint replacements, parameter mappings, and before/after examples.
Evaluators
Migrate trace-level LLM-as-a-judge evaluators to the observation level. If you upgrade your SDKs before migrating, keep supplying trace input/output via the deprecated trace I/O methods (set_current_trace_io() in Python, setActiveTraceIO() in JS/TS) so your existing trace-level evaluators keep receiving data until the new ones are validated.
Exports
Switch blob storage, PostHog, and Mixpanel integrations from the legacy "traces and observations" source to "enriched observations".
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.
Verify
Check the in-app migration view until no required actions remain.
Self-hosted deployments
No forced deadline. v3 continues to receive security patches, and breaking removals only happen in major server releases. Follow the GitHub discussion for the self-hosted v4 go-live date; the migration guide for self-hosted deployments ships with the release. Until then, the self-hosted compatibility matrix shows what each server version supports.
Questions
Ask rollout and migration questions in the dedicated GitHub Discussion; we use that thread for updates and answers.
Last edited
