Upgrade to v2 data APIs
Langfuse is moving data extraction workflows to the high-performance v2 APIs:
- Use Observations API v2 when you need row-level spans, generations, or events.
- Use Metrics API v2 when you need aggregates such as cost, usage, latency, volume, or scores.
The older data retrieval APIs remain available, but are not recommended as the default for new extraction workflows because they are less performant at scale.
Choose the replacement
| Existing usage | Recommended replacement |
|---|---|
List traces with GET /api/public/traces | Query row-level data with GET /api/public/v2/observations, or query aggregates with GET /api/public/v2/metrics |
Fetch one trace with GET /api/public/traces/{traceId} | Query its observations with GET /api/public/v2/observations?traceId=<traceId> |
List observations with GET /api/public/observations | Use GET /api/public/v2/observations |
Fetch one observation with GET /api/public/observations/{observationId} | Use GET /api/public/v2/observations?filter=[{"type":"string","column":"id","operator":"=","value":"<observationId>"}] |
Query aggregates with GET /api/public/metrics | Use GET /api/public/v2/metrics |
If you are extracting large volumes for downstream analytics on a schedule, use Blob Storage Export instead of paginating through an API.
Upgrade SDK usage
Python SDK v4 and JS/TS SDK v5 use v2 data APIs by default.
| SDK | Existing or transitional usage | Recommended usage |
|---|---|---|
| Python | langfuse.api.trace.list(...) for bulk extraction | langfuse.api.observations.get_many(...) or langfuse.api.metrics.get(...) |
| Python | langfuse.api.trace.get("trace-id") for data extraction | langfuse.api.observations.get_many(trace_id="trace-id", ...) |
| Python | langfuse.api.observations_v_2 | langfuse.api.observations |
| Python | langfuse.api.metrics_v_2 | langfuse.api.metrics |
| JS/TS | langfuse.api.trace.list(...) for bulk extraction | langfuse.api.observations.getMany(...) or langfuse.api.metrics.get(...) |
| JS/TS | langfuse.api.trace.get("trace-id") for data extraction | langfuse.api.observations.getMany({ traceId: "trace-id", ... }) |
| JS/TS | langfuse.api.observationsV2 | langfuse.api.observations |
| JS/TS | langfuse.api.metricsV2 | langfuse.api.metrics |
Legacy namespaces remain available when you need the older API behavior:
- Python:
langfuse.api.legacy.observations_v1,langfuse.api.legacy.metrics_v1 - JS/TS:
langfuse.api.legacy.observationsV1,langfuse.api.legacy.metricsV1
Migrate trace extraction
Trace-centric read endpoints are not recommended for extraction workflows because they are less performant at scale. Query observations directly and use traceId to group rows that belong to the same trace.
curl \
-H "Authorization: Basic <BASIC AUTH HEADER>" \
"https://cloud.langfuse.com/api/public/v2/observations?traceId=<traceId>&fields=core,basic,usage,io&limit=1000"from langfuse import get_client
langfuse = get_client()
observations = langfuse.api.observations.get_many(
trace_id="trace-id",
fields="core,basic,usage,io",
limit=1000,
)import { LangfuseClient } from "@langfuse/client";
const langfuse = new LangfuseClient();
const observations = await langfuse.api.observations.getMany({
traceId: "trace-id",
fields: "core,basic,usage,io",
limit: 1000,
});Use parentObservationId to reconstruct an observation tree when needed.
Migrate aggregate queries
Use Metrics API v2 for reporting, dashboards, billing, and monitoring use cases. Prefer aggregates over fetching raw observations and calculating totals yourself.
curl \
-H "Authorization: Basic <BASIC AUTH HEADER>" \
-G \
--data-urlencode 'query={
"view": "observations",
"metrics": [{"measure": "totalCost", "aggregation": "sum"}],
"dimensions": [{"field": "providedModelName"}],
"filters": [],
"fromTimestamp": "2025-12-01T00:00:00Z",
"toTimestamp": "2025-12-16T00:00:00Z",
"orderBy": [{"field": "totalCost_sum", "direction": "desc"}]
}' \
https://cloud.langfuse.com/api/public/v2/metricsThe v2 Metrics API no longer includes the traces view. Use the observations view and trace-level dimensions such as traceName, userId, sessionId, traceRelease, or traceVersion when you need trace-level grouping.
Availability
Observations API v2 and Metrics API v2 are available on Langfuse Cloud. For self-hosted deployments, keep existing calls in place until v2 support is available, and avoid building new extraction workflows on the older endpoints.
