Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

docs(api): warn on sunset ingestion event types (#17453)

Max Deichmann5a31664cbc30
diff --git a/fern/apis/server/definition/ingestion.yml b/fern/apis/server/definition/ingestion.yml
index 9c0d50f5af..e6793f36e8 100644
--- a/fern/apis/server/definition/ingestion.yml
+++ b/fern/apis/server/definition/ingestion.yml
@@ -9,11 +9,19 @@ service:
batch:
availability:
status: deprecated
- message: "On Langfuse Cloud, Langfuse v3 is deprecated and v4-only write mode begins on November 16, 2026. This endpoint is never shut down; it continues to accept score events. Trace and observation events fail only in v4-only write mode, not in dual or legacy mode. Always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, only then send data via the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` (for example with curl); see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). Self-hosted deployments are unaffected by this date; they reject trace and observation events only in v4-only write mode, not dual or legacy."
+ message: "On Langfuse Cloud, this is the deprecated Langfuse v3 ingestion API and it is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs; if you use custom auto-instrumentation, send them to the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` (for example with curl); see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`; all other public APIs may have data delays of several minutes. Self-hosted deployments are unaffected by the November 16 date; this behavior begins only when they enable v4-only write mode."
docs: |
**Legacy endpoint for batch ingestion for Langfuse Observability.**
- This endpoint is never shut down. Trace and observation events are rejected only in v4-only write mode (not dual or legacy); score events continue to be accepted. Always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, only then send traces via the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl. Learn more: https://langfuse.com/integrations/native/opentelemetry
+ This is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types.
+
+ To write scores, prefer `POST /api/public/scores`: https://langfuse.com/docs/api-and-data-platform/features/scores-api
+
+ To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl: https://langfuse.com/integrations/native/opentelemetry
+
+ To read data back, use the v4 read APIs: https://langfuse.com/docs/api-and-data-platform/features/observations-api and https://langfuse.com/docs/metrics/features/metrics-api
+
+ The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes.
Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
@@ -34,7 +42,7 @@ service:
properties:
batch:
type: list<IngestionEvent>
- docs: "Batch of tracing events to be ingested. Discriminated by attribute `type`."
+ docs: "Batch of events to be ingested, discriminated by attribute `type`. From November 16, 2026 on Langfuse Cloud, only `score-create` events are accepted; all other event types are rejected."
metadata:
type: optional<unknown>
docs: Optional. Metadata field used by the Langfuse SDKs for debugging.
@@ -112,37 +120,33 @@ types:
union:
trace-create:
type: TraceEvent
- docs: Creates a new trace. Upserts on id for updates if trace with id exists.
+ docs: "Creates a new trace. Upserts on id for updates if trace with id exists. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
score-create:
type: ScoreEvent
docs: Creates a new score. Upserts on id for updates if score with id exists.
span-create:
type: CreateSpanEvent
- docs: Creates a new span.
+ docs: "Creates a new span. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
span-update:
type: UpdateSpanEvent
- docs: Updates span based on id.
+ docs: "Updates span based on id. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
generation-create:
type: CreateGenerationEvent
- docs: Creates a new generation.
+ docs: "Creates a new generation. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
generation-update:
type: UpdateGenerationEvent
- docs: Updates a generation based on id.
+ docs: "Updates a generation based on id. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
event-create:
type: CreateEventEvent
- docs: Creates an event.
-
- sdk-log:
- type: SDKLogEvent
- docs: Langfuse SDKs only, used for debugging purposes.
+ docs: "Creates an event. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
# both are legacy
observation-create:
type: CreateObservationEvent
- docs: Deprecated event type
+ docs: "Deprecated event type. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
observation-update:
type: UpdateObservationEvent
- docs: Deprecated event type
+ docs: "Deprecated event type. Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
ObservationType:
enum:
@@ -267,10 +271,6 @@ types:
type: optional<boolean>
docs: Make trace publicly accessible via url
- SDKLogBody:
- properties:
- log: unknown
-
ScoreBody:
properties:
id: optional<string>
@@ -355,16 +355,19 @@ types:
docs: Optional. Metadata field used by the Langfuse SDKs for debugging.
TraceEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: TraceBody
CreateObservationEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: ObservationBody
UpdateObservationEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: ObservationBody
@@ -374,32 +377,32 @@ types:
properties:
body: ScoreBody
- SDKLogEvent:
- extends: BaseEvent
- properties:
- body: SDKLogBody
-
CreateGenerationEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: CreateGenerationBody
UpdateGenerationEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: UpdateGenerationBody
CreateSpanEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: CreateSpanBody
UpdateSpanEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: UpdateSpanBody
CreateEventEvent:
+ docs: "Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is shut down on November 16, 2026, except for score events: from that date it accepts only `score-create` events and rejects all other event types, including this one. To write scores, prefer `POST /api/public/scores`; see the [Scores API docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). To write traces and observations, always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, send them to the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl; see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). To read data back, use the v4 read APIs; see the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the [Metrics API docs](https://langfuse.com/docs/metrics/features/metrics-api). The only path to live data is OpenTelemetry ingestion combined with `GET /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other public APIs may have data delays of several minutes."
extends: BaseEvent
properties:
body: CreateEventBody
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index 54d6d395a2..939ee132e6 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -2771,33 +2771,59 @@ paths:
/api/public/ingestion:
post:
description: >-
- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and v4-only
- write mode begins on November 16, 2026. This endpoint is never shut
- down; it continues to accept score events. Trace and observation events
- fail only in v4-only write mode, not in dual or legacy mode. Always
- prefer upgrading to the current Python and JS SDKs. If you use custom
- auto-instrumentation, only then send data via the OpenTelemetry endpoint
- at `POST /api/public/otel/v1/traces` (for example with curl); see the
- [OpenTelemetry integration
- docs](https://langfuse.com/integrations/native/opentelemetry).
- Self-hosted deployments are unaffected by this date; they reject trace
- and observation events only in v4-only write mode, not dual or legacy.
- See the [Langfuse v3 to v4 upgrade
+ **Deprecated:** On Langfuse Cloud, this is the deprecated Langfuse v3
+ ingestion API and it is shut down on November 16, 2026, except for score
+ events: from that date it accepts only `score-create` events and rejects
+ all other event types. To write scores, prefer `POST
+ /api/public/scores`; see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs; if you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` (for
+ example with curl); see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`; all other
+ public APIs may have data delays of several minutes. Self-hosted
+ deployments are unaffected by the November 16 date; this behavior begins
+ only when they enable v4-only write mode. See the [Langfuse v3 to v4
+ upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
**Legacy endpoint for batch ingestion for Langfuse Observability.**
- This endpoint is never shut down. Trace and observation events are
- rejected only in v4-only write mode (not dual or legacy); score events
- continue to be accepted. Always prefer upgrading to the current Python
- and JS SDKs. If you use custom auto-instrumentation, only then send
- traces via the OpenTelemetry endpoint (`POST
- /api/public/otel/v1/traces`), for example with curl. Learn more:
+ This is the deprecated Langfuse v3 ingestion API. It is shut down on
+ November 16, 2026, except for score events: from that date it accepts
+ only `score-create` events and rejects all other event types.
+
+
+ To write scores, prefer `POST /api/public/scores`:
+ https://langfuse.com/docs/api-and-data-platform/features/scores-api
+
+
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl:
https://langfuse.com/integrations/native/opentelemetry
+ To read data back, use the v4 read APIs:
+ https://langfuse.com/docs/api-and-data-platform/features/observations-api
+ and https://langfuse.com/docs/metrics/features/metrics-api
+
+
+ The only path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
+
+
Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
@@ -2876,8 +2902,10 @@ paths:
items:
$ref: '#/components/schemas/IngestionEvent'
description: >-
- Batch of tracing events to be ingested. Discriminated by
- attribute `type`.
+ Batch of events to be ingested, discriminated by attribute
+ `type`. From November 16, 2026 on Langfuse Cloud, only
+ `score-create` events are accepted; all other event types
+ are rejected.
metadata:
nullable: true
description: >-
@@ -13555,18 +13583,6 @@ components:
required:
- type
title: CreateEventEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - sdk-log
- - $ref: '#/components/schemas/SDKLogEvent'
- required:
- - type
- title: SDKLogEvent
- type: object
allOf:
- type: object
@@ -13875,13 +13891,6 @@ components:
type: boolean
nullable: true
description: Make trace publicly accessible via url
- SDKLogBody:
- title: SDKLogBody
- type: object
- properties:
- log: {}
- required:
- - log
ScoreBody:
title: ScoreBody
type: object
@@ -13968,6 +13977,25 @@ components:
TraceEvent:
title: TraceEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/TraceBody'
@@ -13978,6 +14006,25 @@ components:
CreateObservationEvent:
title: CreateObservationEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/ObservationBody'
@@ -13988,6 +14035,25 @@ components:
UpdateObservationEvent:
title: UpdateObservationEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/ObservationBody'
@@ -14005,19 +14071,28 @@ components:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
- SDKLogEvent:
- title: SDKLogEvent
- type: object
- properties:
- body:
- $ref: '#/components/schemas/SDKLogBody'
- required:
- - body
- allOf:
- - $ref: '#/components/schemas/BaseEvent'
CreateGenerationEvent:
title: CreateGenerationEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
@@ -14028,6 +14103,25 @@ components:
UpdateGenerationEvent:
title: UpdateGenerationEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/UpdateGenerationBody'
@@ -14038,6 +14132,25 @@ components:
CreateSpanEvent:
title: CreateSpanEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/CreateSpanBody'
@@ -14048,6 +14161,25 @@ components:
UpdateSpanEvent:
title: UpdateSpanEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/UpdateSpanBody'
@@ -14058,6 +14190,25 @@ components:
CreateEventEvent:
title: CreateEventEvent
type: object
+ description: >-
+ Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
+ shut down on November 16, 2026, except for score events: from that date
+ it accepts only `score-create` events and rejects all other event types,
+ including this one. To write scores, prefer `POST /api/public/scores`;
+ see the [Scores API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
+ To write traces and observations, always prefer upgrading to the current
+ Python and JS SDKs. If you use custom auto-instrumentation, send them to
+ the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
+ example with curl; see the [OpenTelemetry integration
+ docs](https://langfuse.com/integrations/native/opentelemetry). To read
+ data back, use the v4 read APIs; see the [Observations API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
+ and the [Metrics API
+ docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
+ path to live data is OpenTelemetry ingestion combined with `GET
+ /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
+ public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/CreateEventBody'
diff --git a/web/src/__tests__/server/deprecation-signal.servertest.ts b/web/src/__tests__/server/deprecation-signal.servertest.ts
index 94df819317..859c67030b 100644
--- a/web/src/__tests__/server/deprecation-signal.servertest.ts
+++ b/web/src/__tests__/server/deprecation-signal.servertest.ts
@@ -239,12 +239,13 @@ describe("public API deprecation signal", () => {
"POST /api/public/otel/v1/traces",
);
expect(INGESTION_DEPRECATION.message).toContain(
- "Always prefer upgrading to the current Python and JS SDKs",
+ "prefer upgrading to the current Python and JS SDKs",
);
expect(INGESTION_DEPRECATION.message).toContain(
"custom auto-instrumentation",
);
expect(INGESTION_DEPRECATION.message).toContain("curl");
+ expect(INGESTION_DEPRECATION.message).toContain("POST /api/public/scores");
expect(INGESTION_DEPRECATION.message).toContain(
"GET /api/public/v2/observations",
);
diff --git a/web/src/__tests__/server/unit/ingestion-write-mode.servertest.ts b/web/src/__tests__/server/unit/ingestion-write-mode.servertest.ts
new file mode 100644
index 0000000000..0749ec8996
--- /dev/null
+++ b/web/src/__tests__/server/unit/ingestion-write-mode.servertest.ts
@@ -0,0 +1,27 @@
+import { filterBatchForEventsOnly } from "@/src/pages/api/public/ingestion";
+
+describe("legacy ingestion write-mode filter", () => {
+ const scoreEvent = { id: "score", type: "score-create" };
+ const sdkLogEvent = { id: "log", type: "sdk-log" };
+
+ it("allows only score events in v4-only mode", () => {
+ expect(filterBatchForEventsOnly([scoreEvent, sdkLogEvent], true)).toEqual({
+ batchForProcessing: [scoreEvent],
+ rejectedErrors: [
+ expect.objectContaining({
+ id: "log",
+ status: 400,
+ message: "Event type not accepted",
+ error: expect.stringContaining("only accepts score events"),
+ }),
+ ],
+ });
+ });
+
+ it("preserves sdk-log compatibility outside v4-only mode", () => {
+ expect(filterBatchForEventsOnly([sdkLogEvent], false)).toEqual({
+ batchForProcessing: [sdkLogEvent],
+ rejectedErrors: [],
+ });
+ });
+});
diff --git a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts b/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts
index 61dfc71b5d..45813129c0 100644
--- a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts
+++ b/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts
@@ -30,9 +30,16 @@ type OpenApiOperation = {
description?: string;
security?: unknown;
};
+type OpenApiSchema = {
+ description?: string;
+};
type OpenApiDocument = {
paths: Record<string, Record<string, OpenApiOperation>>;
+ components: {
+ schemas: Record<string, OpenApiSchema>;
+ };
};
+type FernUnion = Record<string, { docs?: string; type: string }>;
const definitionDirectory = path.resolve(
process.cwd(),
@@ -118,6 +125,16 @@ describe("OpenAPI deprecations", () => {
);
});
+ // Score writes are the successor the ingestion sunset message points at, so
+ // deprecating them would contradict that guidance.
+ it("keeps the score write endpoint free of a deprecation", () => {
+ const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));
+ const scoreCreate = openApi.paths["/api/public/scores"].post;
+
+ expect(scoreCreate.deprecated).toBeUndefined();
+ expect(scoreCreate.description ?? "").not.toContain("Deprecated:");
+ });
+
it("carries every Fern deprecation message into the operation description", () => {
const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));
@@ -178,8 +195,8 @@ describe("OpenAPI deprecations", () => {
});
// Every family that already stamps `_deprecation` shares V3_NOTICE, so a new
- // family that forgets it would ship without the delay warning.
- it("puts the 10-minute delay on every legacy `_deprecation.message`", () => {
+ // family that forgets it would ship without the live-read delay warning.
+ it("puts the live-read delay notice on every legacy `_deprecation.message`", () => {
const families = [
OBSERVATIONS_V1_DEPRECATION,
TRACES_DEPRECATION,
@@ -196,34 +213,111 @@ describe("OpenAPI deprecations", () => {
}
});
- it("tells legacy ingestion callers to prefer Python and JS SDKs over curl", () => {
+ it("leads with the ingestion sunset and names the write successors", () => {
+ const ingestion = getFernDeprecatedOperations(definitionDirectory).find(
+ ({ method, endpointPath }) =>
+ method === "post" && endpointPath === "/api/public/ingestion",
+ );
+
+ for (const message of [INGESTION_DEPRECATION.message, ingestion?.message]) {
+ expect(message).toContain(`shut down on ${V3_SUNSET_HUMAN}`);
+ expect(message).toContain("except for score events");
+ expect(message).toContain("rejects all other event types");
+ expect(message).toContain("POST /api/public/scores");
+ expect(message).toContain(
+ "prefer upgrading to the current Python and JS SDKs",
+ );
+ expect(message).toContain("custom auto-instrumentation");
+ expect(message).toContain("curl");
+ expect(message).toContain("POST /api/public/otel/v1/traces");
+ expect(message).toContain(
+ "The only path to live data is OpenTelemetry ingestion",
+ );
+ expect(message).toContain(
+ "other public APIs may have data delays of several minutes",
+ );
+ }
+
+ // Read guidance points at the live v2 surfaces and their docs.
expect(INGESTION_DEPRECATION.message).toContain(
- "Always prefer upgrading to the current Python and JS SDKs",
+ "GET /api/public/v2/observations",
);
expect(INGESTION_DEPRECATION.message).toContain(
- "custom auto-instrumentation",
+ "GET /api/public/v2/metrics",
);
- expect(INGESTION_DEPRECATION.message).toContain("curl");
-
- const ingestion = getFernDeprecatedOperations(definitionDirectory).find(
- ({ method, endpointPath }) =>
- method === "post" && endpointPath === "/api/public/ingestion",
+ expect(INGESTION_DEPRECATION.message).toContain(
+ "https://langfuse.com/docs/api-and-data-platform/features/scores-api",
+ );
+ expect(INGESTION_DEPRECATION.message).toContain(
+ "https://langfuse.com/docs/api-and-data-platform/features/observations-api",
);
expect(ingestion?.message).toContain(
- "Always prefer upgrading to the current Python and JS SDKs",
+ "https://langfuse.com/docs/api-and-data-platform/features/scores-api",
);
- expect(ingestion?.message).toContain("custom auto-instrumentation");
- expect(ingestion?.message).toContain("curl");
- expect(INGESTION_DEPRECATION.message).toContain("never shut down");
- expect(INGESTION_DEPRECATION.message).toContain("score events");
- expect(INGESTION_DEPRECATION.message).toContain("v4-only write mode");
- expect(INGESTION_DEPRECATION.message).toContain(
- "not in dual or legacy mode",
+ expect(ingestion?.message).toContain(
+ "https://langfuse.com/docs/api-and-data-platform/features/observations-api",
+ );
+ expect(ingestion?.message).toContain(
+ "https://langfuse.com/docs/metrics/features/metrics-api",
);
- expect(ingestion?.message).toContain("never shut down");
- expect(ingestion?.message).toContain("score events");
- expect(ingestion?.message).toContain("v4-only write mode");
- expect(ingestion?.message).toContain("not in dual or legacy mode");
+ });
+
+ it("warns every sunset ingestion event type in the request body", () => {
+ const ingestionDefinition = parse(
+ fs.readFileSync(path.join(definitionDirectory, "ingestion.yml"), "utf8"),
+ ) as {
+ types: { IngestionEvent: { union: FernUnion } };
+ };
+ const ingestionEvents = ingestionDefinition.types.IngestionEvent.union;
+ const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));
+ const supportedEventTypes = new Set(["score-create"]);
+ const expectedEventTypes = new Set([
+ "trace-create",
+ "score-create",
+ "span-create",
+ "span-update",
+ "generation-create",
+ "generation-update",
+ "event-create",
+ "observation-create",
+ "observation-update",
+ ]);
+
+ expect(new Set(Object.keys(ingestionEvents))).toEqual(expectedEventTypes);
+
+ for (const [eventType, event] of Object.entries(ingestionEvents)) {
+ const generatedSchema = openApi.components.schemas[event.type];
+
+ if (supportedEventTypes.has(eventType)) {
+ expect(event.docs, eventType).not.toContain("Sunset warning");
+ expect(generatedSchema.description ?? "", eventType).not.toContain(
+ "Sunset warning",
+ );
+ continue;
+ }
+
+ // Every rejected event type carries the full endpoint guidance, so a
+ // caller reading one variant does not have to find the endpoint docs.
+ for (const description of [event.docs, generatedSchema.description]) {
+ expect(description, eventType).toContain("Sunset warning");
+ expect(description, eventType).toContain(
+ `shut down on ${V3_SUNSET_HUMAN}`,
+ );
+ expect(description, eventType).toContain(
+ "rejects all other event types, including this one",
+ );
+ expect(description, eventType).toContain("POST /api/public/scores");
+ expect(description, eventType).toContain(
+ "POST /api/public/otel/v1/traces",
+ );
+ expect(description, eventType).toContain(
+ "The only path to live data is OpenTelemetry ingestion",
+ );
+ expect(description, eventType).toContain(
+ "other public APIs may have data delays of several minutes",
+ );
+ }
+ }
});
it("supports deprecated endpoints at a service base path", () => {
diff --git a/web/src/features/public-api/server/deprecations.ts b/web/src/features/public-api/server/deprecations.ts
index 5f9167d1a0..b8e5da3a8f 100644
--- a/web/src/features/public-api/server/deprecations.ts
+++ b/web/src/features/public-api/server/deprecations.ts
@@ -14,7 +14,7 @@ export const V3_SUNSET_HUMAN = "November 16, 2026";
// Shared deprecation reason — references the deprecated Langfuse v3 system
// version (not an API version). Customer-facing wording lives here — edit once.
export const V3_DELAY_NOTICE =
- "Data on this API is delayed by about 10 minutes. Real-time is only OpenTelemetry writes plus v2 observations and v2 metrics reads.";
+ "The only path to live data is OpenTelemetry ingestion combined with GET /api/public/v2/observations and GET /api/public/v2/metrics. All other public APIs may have data delays of several minutes.";
const V3_NOTICE = `On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on ${V3_SUNSET_HUMAN}. ${V3_DELAY_NOTICE}`;
@@ -26,6 +26,7 @@ const REPLACEMENT = {
observationsV2BySession:
"GET /api/public/v2/observations?filter=<urlencoded sessionId filter>&fromStartTime=<from>&toStartTime=<to>",
scoresV3: "GET /api/public/v3/scores",
+ scoreCreate: "POST /api/public/scores",
metricsV2: "GET /api/public/v2/metrics?query=<urlencoded json query>",
otelTraces: "POST /api/public/otel/v1/traces",
experimentItems:
@@ -101,12 +102,11 @@ export const DATASET_RUNS_DEPRECATION: ApiDeprecationInfo = {
sunsetAt: V3_SUNSET_DATE,
};
-// Legacy batch writes of traces/observations → OTLP. This route is never
-// removed: scores (and sdk-log) stay accepted. Trace/observation events are
-// rejected only in v4-only write mode, not dual or legacy — so this family
-// does not use V3_NOTICE ("endpoint will be removed").
+// Legacy batch writes of traces/observations → score writes plus OTLP. Score
+// events survive the sunset date, so this family does not use V3_NOTICE
+// ("endpoint will be removed").
export const INGESTION_DEPRECATION: ApiDeprecationInfo = {
- message: `On Langfuse Cloud, Langfuse v3 is deprecated and v4-only write mode begins on ${V3_SUNSET_HUMAN}. ${V3_DELAY_NOTICE} This endpoint is never shut down; it continues to accept score events. Trace and observation events fail only in v4-only write mode, not in dual or legacy mode. Always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, only then write traces and observations via ${REPLACEMENT.otelTraces} (for example with curl). Retrieve the data via ${REPLACEMENT.observationsV2} and ${REPLACEMENT.metricsV2}.`,
+ message: `On Langfuse Cloud, this is the deprecated Langfuse v3 ingestion API and it is shut down on ${V3_SUNSET_HUMAN}, except for score events: from that date it accepts only score-create events and rejects all other event types. To write scores, prefer ${REPLACEMENT.scoreCreate} (${DOCS.scoresV3}). To write traces and observations, always prefer upgrading to the current Python and JS SDKs; if you use custom auto-instrumentation, send them to ${REPLACEMENT.otelTraces} (for example with curl). To read data back, use ${REPLACEMENT.observationsV2} and ${REPLACEMENT.metricsV2} (${DOCS.observationsV2}). ${V3_DELAY_NOTICE}`,
replacement: REPLACEMENT.otelTraces,
docsUrl: DOCS.otelMigration,
sunsetAt: V3_SUNSET_DATE,
diff --git a/web/src/pages/api/public/ingestion.ts b/web/src/pages/api/public/ingestion.ts
index 2ef3af1198..c3ac2adab3 100644
--- a/web/src/pages/api/public/ingestion.ts
+++ b/web/src/pages/api/public/ingestion.ts
@@ -171,9 +171,9 @@ export default async function handler(
await telemetry();
- // V4 events_only mode: refuse trace/observation events because their
- // writes would land in the legacy ClickHouse tables this deployment no
- // longer reads. Scores and SDK logs are unaffected and pass through.
+ // V4 events_only mode: refuse every non-score event because trace and
+ // observation writes target legacy ClickHouse tables this deployment
+ // no longer reads. SDK logs are no longer accepted in this mode.
// Reject per-event so a mixed batch still processes its score events.
const isEventsOnlyMode =
env.LANGFUSE_MIGRATION_V4_WRITE_MODE === "events_only";
@@ -276,13 +276,9 @@ export default async function handler(
}
}
-// Event types that may continue to ingest in V4 events_only mode. Scores keep
-// their own ClickHouse table (no legacy traces/observations write); SDK logs
-// are non-persisting.
-const EVENTS_ONLY_ALLOWED_TYPES = new Set<string>([
- eventTypes.SCORE_CREATE,
- eventTypes.SDK_LOG,
-]);
+// Scores keep their own ClickHouse table and are the only event type accepted
+// by this endpoint in V4 events_only mode.
+const EVENTS_ONLY_ALLOWED_TYPES = new Set<string>([eventTypes.SCORE_CREATE]);
const TRACE_OR_OBSERVATION_EVENT_TYPES = new Set<string>(
Object.values(eventTypes).filter(
@@ -302,7 +298,7 @@ const EVENTS_ONLY_INGESTION_REMEDIATION = [
`Docs: ${EVENTS_ONLY_INGESTION_DOCS_URL}`,
].join(" ");
-function filterBatchForEventsOnly(
+export function filterBatchForEventsOnly(
batch: unknown[],
isEventsOnlyMode: boolean,
): {
@@ -343,7 +339,7 @@ function filterBatchForEventsOnly(
id,
status: 400,
message: "Event type not accepted",
- error: `Event type "${type ?? "unknown"}" is not accepted by /api/public/ingestion when LANGFUSE_MIGRATION_V4_WRITE_MODE is events_only. This endpoint only accepts score and log events. ${EVENTS_ONLY_INGESTION_REMEDIATION}`,
+ error: `Event type "${type ?? "unknown"}" is not accepted by /api/public/ingestion when LANGFUSE_MIGRATION_V4_WRITE_MODE is events_only. This endpoint only accepts score events. ${EVENTS_ONLY_INGESTION_REMEDIATION}`,
});
}
}