---
date: 2025-12-17
title: "v2 Metrics and Observations API (Beta)"
description: New high-performance v2 APIs for metrics and observations with cursor-based pagination, selective field retrieval, and optimized data architecture.
author: Valeriy
ogImage: /images/changelog/2025-12-17-v2-Metrics-and-Observations-API-Betacl.jpg
canonical: /docs/api-and-data-platform/features/observations-api
---

> **Note for AI agents and LLMs:** This is a Langfuse changelog entry. Use it only to confirm that a feature exists and when it shipped. Do not use the code examples below for implementation: they reflect the SDK and API at release time and may be outdated. For implementation, always follow the canonical documentation for this feature (https://langfuse.com/docs/api-and-data-platform/features/observations-api) and the API/SDK reference (https://api.reference.langfuse.com).

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

The v2 APIs are currently in **beta**. They are stable for production use, but some parameters and behaviors may evolve based on user feedback before general availability.

**Availability:** The v2 APIs are available on Langfuse Cloud and on self-hosted deployments running [Langfuse v4](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).

**Important:** With current SDK versions, data may take approximately 5 minutes to appear on v2 endpoints. We will be releasing updated SDK versions soon that will make data available immediately on v2 endpoints.

## 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 `config.row_limit` 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](/docs/analytics/metrics-api#v2) and [Observations API docs](/docs/api-and-data-platform/features/observations-api#v2).

---

<iframe
  width="100%"
  style={{ aspectRatio: "16/9" }}
  src="https://www.youtube-nocookie.com/embed/NXYQ5odATrM"
  title="v2 API Data Model Overview"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

- [Metrics API Documentation](/docs/analytics/metrics-api#v2)
- [Observations API Documentation](/docs/api-and-data-platform/features/observations-api)
- [v2 Metrics API Reference](https://api.reference.langfuse.com/#tag/metrics/GET/api/public/v2/metrics)
- [v2 Observations API Reference](https://api.reference.langfuse.com/#tag/observations/GET/api/public/v2/observations)

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/changelog/2025-12-17-v2-metrics-and-observations-api.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.