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

Python SDK v4 and JS/TS SDK v5 use v2 data APIs by default.

Existing usage	REST API replacement	Python SDK replacement	JS/TS SDK replacement
List traces with `GET /api/public/traces`	Query row-level data with `GET /api/public/v2/observations`, or aggregates with `GET /api/public/v2/metrics`	`langfuse.api.observations.get_many(...)` or `langfuse.api.metrics.get(...)`	`langfuse.api.observations.getMany(...)` or `langfuse.api.metrics.get(...)`
Fetch one trace with `GET /api/public/traces/{traceId}`	Query its observations with `GET /api/public/v2/observations?traceId=<traceId>`	`langfuse.api.observations.get_many(trace_id="trace-id", ...)`	`langfuse.api.observations.getMany({ traceId: "trace-id", ... })`
List observations with `GET /api/public/observations`	Use `GET /api/public/v2/observations`	`langfuse.api.observations.get_many(...)`	`langfuse.api.observations.getMany(...)`
Fetch one observation with `GET /api/public/observations/{observationId}`	Use `GET /api/public/v2/observations?filter=<id filter>`	`langfuse.api.observations.get_many(filter="<id filter>")`	`langfuse.api.observations.getMany({ filter: JSON.stringify(<id filter>) })`
Query aggregates with `GET /api/public/metrics`	Use `GET /api/public/v2/metrics`	`langfuse.api.metrics.get(...)`	`langfuse.api.metrics.get(...)`

For observation lookups, use this <id filter>:

[
  {
    "type": "string",
    "column": "id",
    "operator": "=",
    "value": "<observationId>"
  }
]

If you use transitional SDK namespaces, replace Python langfuse.api.observations_v_2 / langfuse.api.metrics_v_2 with langfuse.api.observations / langfuse.api.metrics, and replace JS/TS langfuse.api.observationsV2 / langfuse.api.metricsV2 with langfuse.api.observations / langfuse.api.metrics.

If you are extracting large volumes for downstream analytics on a schedule, use Blob Storage Export instead of paginating through an API.

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/metrics

The 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.

Was this page helpful?

Upgrade to v2 data APIs

Choose the replacement

Migrate trace extraction

Migrate aggregate queries

Availability

On this page