Metrics API

GET /api/public/v2/metrics

The Metrics API enables you to retrieve customized analytics from your Langfuse data. This endpoint allows you to specify dimensions, metrics, filters, and time granularity to build powerful custom reports and dashboards for your LLM applications.

The deprecated GET /api/public/metrics and GET /api/public/metrics/daily endpoints are documented in the Deprecated APIs reference; to move off them, see Migration of deprecated APIs.

Metrics API v2

Where is this feature available?

Hobby
Available
Core
Available
Pro
Available
Enterprise
Available
Self Hosted
Langfuse v4+

Data availability: Data from older SDKs (langfuse-python < 4.0.0, langfuse-js < 5.0.0) or direct OpenTelemetry exporters that do not send x-langfuse-ingestion-version: 4 can be delayed by up to 10 minutes on v2 endpoints. Upgrade to Python SDK v4.7.0+ or JS/TS SDK v5.4.0+, or set that header on your OTEL span exporter, to see new data in real time.

On self-hosted Langfuse v3, use the v1 Metrics API instead; see the self-hosted compatibility matrix.

GET /api/public/v2/metrics

The v2 Metrics API provides significant performance improvements through an optimized data architecture built on a new events table schema that minimizes database work per query.

Key Changes from v1

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

Available Views in v2

View	Description
`observations`	Query observation-level data with optional trace-level aggregations
`scores-numeric`	Query numeric and boolean scores
`scores-categorical`	Query categorical (string) scores

Row Limit

The v2 Metrics API enforces a default config.row_limit of 100 rows per query to ensure consistent performance. You can specify a custom config.row_limit in your query to override this default, up to a maximum of 1,000 rows.

High Cardinality Dimensions

Certain dimensions like id, traceId, userId, and sessionId cannot be used for grouping in the v2 Metrics API. Grouping by these high cardinality fields is extremely expensive and rarely useful in practice. These dimensions remain available for filtering.

Ordering by metrics

When ordering by an aggregated metric, use the returned metric field name in the format {aggregation}_{measure}, for example sum_totalCost for { "measure": "totalCost", "aggregation": "sum" }. When ordering by the time dimension, use the returned field name time_dimension.

Example: Most expensive models used in observations

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": "sum_totalCost", "direction": "desc"}],
    "config": {"row_limit": 1000}
  }' \
  https://cloud.langfuse.com/api/public/v2/metrics

API Reference: See the full v2 Metrics API Reference for all available parameters, response schemas, and interactive examples.

Was this page helpful?

On this page