Skip to content

Commit e83a1fe

Browse files
maxdeichmannmaxdeichmann
authored
Guide users to v2 data APIs (#2971)
1 parent 01240b2 commit e83a1fe

6 files changed

Lines changed: 309 additions & 238 deletions

File tree

‎content/docs/api-and-data-platform/features/observations-api.mdx‎

Lines changed: 75 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ If you need aggregated metrics (e.g., total cost, token counts, or trace volumes
1212

1313
For general information about API authentication, base URLs, and SDK access, see the [Public API documentation](/docs/api-and-data-platform/features/public-api).
1414

15+
<Callout type="info">
16+
17+
Older trace and observation read APIs remain available, but are not recommended as the default for new data extraction workflows because they are less performant at scale. Use Observations API v2 for row-level data extraction.
18+
19+
</Callout>
20+
1521
## Observations API v2 [#v2]
1622

1723
<Callout type="warning">
@@ -28,6 +34,19 @@ GET /api/public/v2/observations
2834

2935
The v2 Observations API is a redesigned endpoint optimized for high-performance data retrieval. It addresses the performance bottlenecks of the v1 API by minimizing the work Langfuse has to perform per query.
3036

37+
### Upgrade from older trace and observation reads [#upgrade-from-older-reads]
38+
39+
| Existing usage | Recommended replacement |
40+
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
41+
| List traces with `GET /api/public/traces` | Use `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>` and group rows by `traceId` |
42+
| Fetch one trace with `GET /api/public/traces/{traceId}` | Use `GET /api/public/v2/observations?traceId=<traceId>&fromStartTime=<from>&toStartTime=<to>` |
43+
| List observations with `GET /api/public/observations` | Use `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>` |
44+
| Fetch one observation with `GET /api/public/observations/{observationId}` | Use `GET /api/public/v2/observations?filter=<id filter>&fromStartTime=<from>&toStartTime=<to>` |
45+
46+
Always include `fromStartTime` and `toStartTime` to keep each request bounded.
47+
48+
The v2 Observations API returns observation rows, not full trace objects. Group rows by `traceId` when you need to reconstruct trace activity, and use [Metrics API v2](/docs/metrics/features/metrics-api#v2) for aggregate reporting with trace-level dimensions such as `traceName`, `traceRelease`, or `traceVersion`. For single-observation lookups, pass a URL-encoded `filter` condition on the `id` column; see the [v2 Observations API Reference](https://api.reference.langfuse.com/#tag/observationsv2/GET/api/public/v2/observations) for the filter schema.
49+
3150
### Key Improvements
3251

3352
**1. Selective Field Retrieval**
@@ -154,63 +173,63 @@ With all fields included
154173

155174
```json
156175
{
157-
"data": [
158-
{
159-
"id": "support-chat-7-950dc53a-gen",
160-
"traceId": "support-chat-7-950dc53a",
161-
"startTime": "2025-12-17T16:09:00.875Z",
162-
"projectId": "7a88fb47-b4e2-43b8-a06c-a5ce950dc53a",
163-
"parentObservationId": null,
164-
"type": "GENERATION",
165-
"endTime": "2025-12-17T16:09:01.456Z",
166-
"name": "llm-generation",
167-
"level": "DEFAULT",
168-
"statusMessage": "",
169-
"version": "",
170-
"environment": "default",
171-
"completionStartTime": "2025-12-17T16:09:00.995Z",
172-
"createdAt": "2025-12-17T16:09:00.875Z",
173-
"updatedAt": "2025-12-17T16:09:01.456Z",
174-
"input": "{\"messages\":[{\"role\":\"user\",\"content\":\"Perfect.\"}]}",
175-
"output": "{\"role\":\"assistant\",\"content\":\"You're all set. Have a great day!\"}",
176-
"metadata": {},
177-
"model": "gpt-4o",
178-
"internalModelId": "",
179-
"modelParameters": {
180-
"temperature": 0.2
181-
},
182-
"usageDetails": {
183-
"input": 98,
184-
"output": 68,
185-
"total": 166
186-
},
187-
"inputUsage": 98,
188-
"outputUsage": 68,
189-
"totalUsage": 166,
190-
"costDetails": {
191-
"input": 0.000196,
192-
"output": 0.000204,
193-
"total": 0.00083
194-
},
195-
"inputCost": 0.000196,
196-
"outputCost": 0.000204,
197-
"totalCost": 0.00083,
198-
"promptId": "",
199-
"promptName": "",
200-
"promptVersion": null,
201-
"latency": 0.581,
202-
"timeToFirstToken": 0.12,
203-
"userId": "",
204-
"sessionId": "support-chat-session",
205-
"modelId": null,
206-
"inputPrice": null,
207-
"outputPrice": null,
208-
"totalPrice": null
209-
}
210-
],
211-
"meta": {
212-
"cursor": "eyJsYXN0U3RhcnRUaW1lVG8iOiIyMDI1LTEyLTE3VDE2OjA5OjAwLjg3NVoiLCJsYXN0VHJhY2VJZCI6InN1cHBvcnQtY2hhdC03LTk1MGRjNTNhIiwibGFzdElkIjoic3VwcG9ydC1jaGF0LTctOTUwZGM1M2EtZ2VuIn0="
176+
"data": [
177+
{
178+
"id": "support-chat-7-950dc53a-gen",
179+
"traceId": "support-chat-7-950dc53a",
180+
"startTime": "2025-12-17T16:09:00.875Z",
181+
"projectId": "7a88fb47-b4e2-43b8-a06c-a5ce950dc53a",
182+
"parentObservationId": null,
183+
"type": "GENERATION",
184+
"endTime": "2025-12-17T16:09:01.456Z",
185+
"name": "llm-generation",
186+
"level": "DEFAULT",
187+
"statusMessage": "",
188+
"version": "",
189+
"environment": "default",
190+
"completionStartTime": "2025-12-17T16:09:00.995Z",
191+
"createdAt": "2025-12-17T16:09:00.875Z",
192+
"updatedAt": "2025-12-17T16:09:01.456Z",
193+
"input": "{\"messages\":[{\"role\":\"user\",\"content\":\"Perfect.\"}]}",
194+
"output": "{\"role\":\"assistant\",\"content\":\"You're all set. Have a great day!\"}",
195+
"metadata": {},
196+
"model": "gpt-4o",
197+
"internalModelId": "",
198+
"modelParameters": {
199+
"temperature": 0.2
200+
},
201+
"usageDetails": {
202+
"input": 98,
203+
"output": 68,
204+
"total": 166
205+
},
206+
"inputUsage": 98,
207+
"outputUsage": 68,
208+
"totalUsage": 166,
209+
"costDetails": {
210+
"input": 0.000196,
211+
"output": 0.000204,
212+
"total": 0.00083
213+
},
214+
"inputCost": 0.000196,
215+
"outputCost": 0.000204,
216+
"totalCost": 0.00083,
217+
"promptId": "",
218+
"promptName": "",
219+
"promptVersion": null,
220+
"latency": 0.581,
221+
"timeToFirstToken": 0.12,
222+
"userId": "",
223+
"sessionId": "support-chat-session",
224+
"modelId": null,
225+
"inputPrice": null,
226+
"outputPrice": null,
227+
"totalPrice": null
213228
}
229+
],
230+
"meta": {
231+
"cursor": "eyJsYXN0U3RhcnRUaW1lVG8iOiIyMDI1LTEyLTE3VDE2OjA5OjAwLjg3NVoiLCJsYXN0VHJhY2VJZCI6InN1cHBvcnQtY2hhdC03LTk1MGRjNTNhIiwibGFzdElkIjoic3VwcG9ydC1jaGF0LTctOTUwZGM1M2EtZ2VuIn0="
232+
}
214233
}
215234
```
216235

@@ -219,13 +238,3 @@ With all fields included
219238
**API Reference:** See the full [v2 Observations API Reference](https://api.reference.langfuse.com/#tag/observationsv2/GET/api/public/v2/observations) for all available parameters, response schemas, and interactive examples.
220239

221240
</Callout>
222-
223-
## Observations API v1 [#v1]
224-
225-
```
226-
GET /api/public/observations
227-
```
228-
229-
The v1 Observations API remains available for existing integrations. For new implementations, we recommend using the v2 API for better performance.
230-
231-
See the [API Reference](https://api.reference.langfuse.com/#tag/observation/GET/api/public/observations) for v1 documentation.

‎content/docs/api-and-data-platform/features/public-api.mdx‎

Lines changed: 57 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -79,15 +79,19 @@ curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects
7979

8080
## Access via SDKs
8181

82-
Both the Langfuse [Python SDK](/docs/sdk/python/decorators) and the [JS/TS SDK](/docs/sdk/typescript/guide) provide a strongly-typed wrapper around our public REST API for your convenience. The API methods are accessible via the `api` property on the Langfuse client instance in both SDKs.
82+
Both the Langfuse [Python SDK](/docs/sdk/python/sdk-v3) and the [JS/TS SDK](/docs/sdk/typescript/guide) provide a strongly-typed wrapper around our public REST API for your convenience. The API methods are accessible via the `api` property on the Langfuse client instance in both SDKs.
8383

8484
You can use your editor's Intellisense to explore the API methods and their parameters.
8585

8686
<Callout type="info">
8787

8888
In Python SDK v4 and JS/TS SDK v5, the high-performance resources are the
8989
defaults: `api.observations`, `api.scores`, and `api.metrics`. Legacy v1
90-
resources moved under `api.legacy.*` (Python: `*_v1`, JS/TS: `*V1`).
90+
resources moved under `api.legacy.*` (Python: `*_v1`, JS/TS: `*V1`). See
91+
[Query via SDKs](/docs/api-and-data-platform/features/query-via-sdk) for SDK examples.
92+
93+
Observations API v2 and Metrics API v2 are currently Cloud-only. For self-hosted
94+
deployments, use the endpoints available in your Langfuse version.
9195

9296
</Callout>
9397

@@ -106,12 +110,25 @@ When using the [Python SDK](/docs/sdk/python/sdk-v3):
106110
from langfuse import get_client
107111

108112
langfuse = get_client()
109-
...
110-
# fetch a trace
111-
langfuse.api.trace.get(trace_id)
112113

113-
# async client via asyncio
114-
await langfuse.async_api.trace(trace_id)
114+
# Retrieve row-level observations via Observations API v2
115+
observations = langfuse.api.observations.get_many(
116+
trace_id="trace-id",
117+
fields="core,basic,usage",
118+
limit=100,
119+
)
120+
121+
# Retrieve aggregates via Metrics API v2
122+
metrics = langfuse.api.metrics.get(query="""
123+
{
124+
"view": "observations",
125+
"metrics": [{"measure": "totalCost", "aggregation": "sum"}],
126+
"dimensions": [{"field": "providedModelName"}],
127+
"filters": [],
128+
"fromTimestamp": "2025-05-01T00:00:00Z",
129+
"toTimestamp": "2025-05-13T00:00:00Z"
130+
}
131+
""")
115132

116133
# explore more endpoints via Intellisense
117134
langfuse.api.*
@@ -126,9 +143,25 @@ await langfuse.async_api.*
126143
import { LangfuseClient } from '@langfuse/client';
127144

128145
const langfuse = new LangfuseClient();
129-
...
130-
// fetch a trace
131-
await langfuse.api.trace.get(traceId);
146+
147+
// Retrieve row-level observations via Observations API v2
148+
const observations = await langfuse.api.observations.getMany({
149+
traceId: "trace-id",
150+
fields: "core,basic,usage",
151+
limit: 100,
152+
});
153+
154+
// Retrieve aggregates via Metrics API v2
155+
const metrics = await langfuse.api.metrics.get({
156+
query: JSON.stringify({
157+
view: "observations",
158+
metrics: [{ measure: "totalCost", aggregation: "sum" }],
159+
dimensions: [{ field: "providedModelName" }],
160+
filters: [],
161+
fromTimestamp: "2025-05-01T00:00:00Z",
162+
toTimestamp: "2025-05-13T00:00:00Z"
163+
})
164+
});
132165

133166
// explore more endpoints via Intellisense
134167
langfuse.api.*
@@ -189,16 +222,27 @@ try {
189222
## Ingest Traces via the API
190223

191224
<Callout type="info">
192-
The OpenTelemetry Endpoint will replace the Ingestion API in the future. Therefore, it is strongly recommended to switch to the OpenTelemetry Endpoint for trace ingestion. Please refer to the [OpenTelemetry docs](/integrations/native/opentelemetry) for more information.
225+
The OpenTelemetry Endpoint will replace the Ingestion API in the future.
226+
Therefore, it is strongly recommended to switch to the OpenTelemetry Endpoint
227+
for trace ingestion. Please refer to the [OpenTelemetry
228+
docs](/integrations/native/opentelemetry) for more information.
193229
</Callout>
194230

195231
- [OpenTelemetry Traces Ingestion Endpoint](https://api.reference.langfuse.com/#tag/opentelemetry/POST/api/public/otel/v1/traces) implements the OTLP/HTTP specification for trace ingestion, providing native OpenTelemetry integration for Langfuse Observability.
196232
- (Legacy) [Ingestion API](https://api.reference.langfuse.com/#tag/ingestion/POST/api/public/ingestion) allows trace ingestion using an API.
197233

198234
## Retrieve Data via the API
199235

200-
- [Observations API](/docs/api-and-data-platform/features/observations-api) - Retrieve observation data (spans, generations, events) from Langfuse for use in custom workflows, evaluation pipelines, and analytics. The v2 API offers high-performance data retrieval with cursor-based pagination and selective field retrieval.
201-
- [Metrics API](/docs/metrics/features/metrics-api) - Retrieve aggregated analytics and metrics from your Langfuse data. Query across different views (observations, scores) with customizable dimensions, metrics, filters, and time granularity for powerful custom reports and dashboards.
236+
For new data extraction workflows, use the v2 data APIs:
237+
238+
- [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) - Retrieve observation data (spans, generations, events) from Langfuse for custom workflows, evaluation pipelines, and analytics.
239+
- [Metrics API v2](/docs/metrics/features/metrics-api#v2) - Retrieve aggregated analytics and metrics from your Langfuse data.
240+
241+
<Callout type="info">
242+
243+
Older trace, observation, and metrics read APIs remain available, but are not recommended as the default for new extraction workflows because they are less performant at scale. See [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) for row-level data and [Metrics API v2](/docs/metrics/features/metrics-api#v2) for aggregates.
244+
245+
</Callout>
202246

203247
## Alternatives
204248

0 commit comments

Comments
 (0)