2

New high-performance v2 APIs for metrics and observations with cursor-based pagination, selective field retrieval, and optimized data architecture.

Why v2? The v1 /public/traces and /public/observations endpoints have been among the most resource-intensive APIs to serve. v2 addresses performance issues: no single way to request partial data, offset pagination doesn't scale, and JSON parsing overhead. v2 is built on an optimized immutable data model that requires fewer joins and eliminates deduplication at query time.

Metrics API v2 (GET /api/public/v2/metrics) - Built on optimized data model with significantly faster query performance. The traces view is no longer available in v2; use the observations view instead. Default limit of 100 rows per query. High cardinality dimensions like id, traceId, userId, and sessionId can no longer be used for grouping in v2, though remain available for filtering.

Observations API v2 (GET /api/public/v2/observations) - Redesigned endpoint with selective field retrieval (specify field groups: core, basic, io, usage), cursor-based pagination, optimized I/O handling (returns strings by default; set parseIoAsJson: true when needed), and stricter limits (default 50, max 1,000).

Migration Notes: v2 APIs are additive - v1 endpoints remain available. Update API calls to use /api/public/v2/ prefix, use fields parameter to specify field groups, replace page-based pagination with cursor-based pagination, and note that parseIoAsJson defaults to false in v2 (v1 always parsed as JSON).

Status: Cloud-only (Beta), currently in beta on Langfuse Cloud. Self-hosted migration path in development. With current SDK versions, data may take ~5 minutes to appear on v2 endpoints; updated SDK versions coming soon.