← 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 /api/public/v2/ prefix
2. Use the fields parameter to specify which field groups you need
3. Replace page-based pagination with cursor-based pagination
4. Note that parseIoAsJson defaults to false in v2 (v1 always parsed I/O as JSON)

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.