← Back to changelog

December 17, 2025

v2 Metrics and Observations API (Beta)

Valeriy Meleshkin

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

We're releasing new v2 endpoints for our Metrics and Observations APIs, designed from the ground up for performance at scale.

Why v2?

The v1 /public/traces and /public/observations endpoints have been among the most resource-intensive APIs to serve. After analyzing usage patterns, we identified several opportunities to dramatically reduce query overhead:

1. No single way to request partial data - The v1 API always returns complete rows with I/O, usage, and metadata even when only a few fields are needed. Traces v1 endpoint supports fields parameter, but it is too coarse-grained.
2. Offset pagination doesn't scale - Page-based pagination makes database do more work than strictly necessary.
3. JSON parsing is expensive - Automatic JSON parsing of input/output adds overhead even when raw strings suffice

The v2 APIs address all of these issues. Additionally, v2 is built on top of a new immutable data model that is inherently faster - it requires fewer joins and eliminates the need for deduplication at query time.

What's New

Metrics API v2

GET /api/public/v2/metrics

Built on an optimized data model, the v2 Metrics API delivers significantly faster query performance.

The traces view is no longer available in v2. Instead, use the observations view which is both faster and more powerful.

Row limit - Default limit of 100 rows per query ensures consistent performance. Override with a custom rowLimit in your query.

High cardinality dimensions - Certain dimensions like id, traceId, userId, and sessionId can no longer be used for grouping in the v2 Metrics API. Grouping by these high cardinality fields is not performant and rarely useful in practice. These dimensions remain available for filtering.

Observations API v2

GET /api/public/v2/observations

A redesigned endpoint for high-performance observation retrieval:

• Selective field retrieval - Specify which field groups you need (e.g., core, basic, io, usage). Defaults to core and basic if not specified
• Cursor-based pagination - Consistent performance regardless of pagination depth
• Optimized I/O handling - Returns I/O as strings by default; set parseIoAsJson: true only when needed
• Stricter limits - Default limit of 50 (max 1,000). With cursor based pagination, large result sets can be efficiently retrieved in smaller chunks, while less work is required per chunk.

Migration Notes

The v2 APIs are additive - v1 endpoints remain available and unchanged. When ready to migrate:

1. Update your API calls to use the /api/public/v2/ prefix.

   • Observations: /api/public/v2/observations
   • Metrics: /api/public/v2/metrics

2. Replace page-based pagination with cursor-based pagination.

   • Use the cursor returned in the response meta object to fetch the next page.

3. Add selective field retrieval on Observations API requests.

   • Use the fields query parameter to request only the data you need, for example core, basic, and usage.
   • Example API request: GET /api/public/v2/observations?fields=core,basic&limit=100
   • Example Python SDK call: langfuse.api.observations.get_many(fields="core,basic,usage")

4. Review the new defaults and limits before rolling out.

   • parseIoAsJson now defaults to false in v2.
   • The Observations API default limit is 50 and the maximum limit is 1,000.
   • The v2 APIs are currently Cloud-only and, with current SDK versions, data may take around 5 minutes to appear.

5. Check that your SDKs and server version are compatible before switching SDK namespaces.

   • Use the latest SDKs if possible.
   • At minimum, use Langfuse server v3.133.0 for the Observations endpoint and v3.137.0 for the Metrics endpoint.
   • For SDK access, use at least JS/TS SDK v4.5.1 or Python SDK v3.11.1.
   • In Python SDK v4+ and JS/TS SDK v5+, the v2 endpoints are the defaults under langfuse.api.observations and langfuse.api.metrics.
   • In older compatible SDKs, use the transitional v2 namespaces (langfuse.api.observations_v_2 / langfuse.api.observationsV2 and langfuse.api.metrics_v_2 / langfuse.api.metricsV2).
   • If you are self-hosting Langfuse, continue using the legacy v1 namespaces for now (langfuse.api.legacy.observations_v1 / langfuse.api.legacy.observationsV1 and langfuse.api.legacy.metrics_v1 / langfuse.api.legacy.metricsV1).
   • Direct API calls do not depend on SDK version as long as you call the v2 endpoint directly.

Using v1 /api/public/traces? Consider v2 /api/public/v2/observations instead - it's significantly faster and covers most use cases.

Learn more

For full documentation, see the Metrics API docs and Observations API docs.