Skip to content

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

docs(api): say real-time data is only OTel plus v2 observations and metrics (#17468)

Max Deichmanncdc9c1d1b95f
diff --git a/fern/apis/server/definition/api.yml b/fern/apis/server/definition/api.yml
index 9cff09d111..f36329d7b6 100644
--- a/fern/apis/server/definition/api.yml
+++ b/fern/apis/server/definition/api.yml
@@ -1,5 +1,9 @@
name: langfuse
docs: |
+ ## Real-time data
+
+ The only real-time path to get tracing data is to ingest via OpenTelemetry (`POST /api/public/otel/v1/traces`) and retrieve via Observations API v2 (`GET /api/public/v2/observations`) and Metrics API v2 (`GET /api/public/v2/metrics`). Other public API write and read endpoints can delay data by about 10 minutes. Direct OpenTelemetry exporters must send the `x-langfuse-ingestion-version: 4` header; current Python and JS SDKs already do. See the [Public API docs](https://langfuse.com/docs/api-and-data-platform/features/public-api) and [real-time ingestion](https://langfuse.com/integrations/native/opentelemetry.md#real-time-ingestion).
+
## Authentication
Authenticate with the API using [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication), get API keys in the project settings:
diff --git a/fern/apis/server/definition/metrics.yml b/fern/apis/server/definition/metrics.yml
index a11c9f4fa5..e291112117 100644
--- a/fern/apis/server/definition/metrics.yml
+++ b/fern/apis/server/definition/metrics.yml
@@ -10,6 +10,8 @@ service:
docs: |
Get metrics from the Langfuse project using a query object. V2 endpoint with optimized performance.
+ Together with OpenTelemetry ingestion and Observations API v2, this is the only real-time read path. Other public API endpoints can delay data by about 10 minutes.
+
## V2 Differences
- Supports `observations`, `scores-numeric`, `scores-boolean`, and `scores-categorical` views only (traces view not supported)
- Direct access to tags and release fields on observations
diff --git a/fern/apis/server/definition/observations.yml b/fern/apis/server/definition/observations.yml
index 2e3375a558..09ba59e2d7 100644
--- a/fern/apis/server/definition/observations.yml
+++ b/fern/apis/server/definition/observations.yml
@@ -9,6 +9,8 @@ service:
docs: |
Get a list of observations with cursor-based pagination and flexible field selection.
+ Together with OpenTelemetry ingestion and Metrics API v2, this is the only real-time read path. Other public API endpoints can delay data by about 10 minutes.
+
## Cursor-based Pagination
This endpoint uses cursor-based pagination for efficient traversal of large datasets.
The cursor is returned in the response metadata and should be passed in subsequent requests
diff --git a/fern/apis/server/definition/opentelemetry.yml b/fern/apis/server/definition/opentelemetry.yml
index 7c41a7e035..3ff6359812 100644
--- a/fern/apis/server/definition/opentelemetry.yml
+++ b/fern/apis/server/definition/opentelemetry.yml
@@ -9,6 +9,8 @@ service:
This endpoint implements the OTLP/HTTP specification for trace ingestion, providing native OpenTelemetry integration for Langfuse Observability.
+ Together with Observations API v2 and Metrics API v2, this is the only real-time write path. Other public API endpoints can delay data by about 10 minutes. Direct exporters must send `x-langfuse-ingestion-version: 4`; current Python and JS SDKs already do.
+
**Supported Formats:**
- Binary Protobuf: `Content-Type: application/x-protobuf`
- JSON Protobuf: `Content-Type: application/json`
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index 939ee132e6..fa22d16a82 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -3,6 +3,21 @@ info:
title: server
version: ''
description: >-
+ ## Real-time data
+
+
+ The only real-time path to get tracing data is to ingest via OpenTelemetry
+ (`POST /api/public/otel/v1/traces`) and retrieve via Observations API v2
+ (`GET /api/public/v2/observations`) and Metrics API v2 (`GET
+ /api/public/v2/metrics`). Other public API write and read endpoints can
+ delay data by about 10 minutes. Direct OpenTelemetry exporters must send the
+ `x-langfuse-ingestion-version: 4` header; current Python and JS SDKs already
+ do. See the [Public API
+ docs](https://langfuse.com/docs/api-and-data-platform/features/public-api)
+ and [real-time
+ ingestion](https://langfuse.com/integrations/native/opentelemetry.md#real-time-ingestion).
+
+
## Authentication
@@ -3731,6 +3746,11 @@ paths:
with optimized performance.
+ Together with OpenTelemetry ingestion and Observations API v2, this is
+ the only real-time read path. Other public API endpoints can delay data
+ by about 10 minutes.
+
+
## V2 Differences
- Supports `observations`, `scores-numeric`, `scores-boolean`, and
@@ -4309,6 +4329,11 @@ paths:
field selection.
+ Together with OpenTelemetry ingestion and Metrics API v2, this is the
+ only real-time read path. Other public API endpoints can delay data by
+ about 10 minutes.
+
+
## Cursor-based Pagination
This endpoint uses cursor-based pagination for efficient traversal of
@@ -4754,6 +4779,12 @@ paths:
Observability.
+ Together with Observations API v2 and Metrics API v2, this is the only
+ real-time write path. Other public API endpoints can delay data by about
+ 10 minutes. Direct exporters must send `x-langfuse-ingestion-version:
+ 4`; current Python and JS SDKs already do.
+
+
**Supported Formats:**
- Binary Protobuf: `Content-Type: application/x-protobuf`