Metrics API
- HobbyAvailable
- CoreAvailable
- ProAvailable
- EnterpriseAvailable
- Self HostedLangfuse v4+
GET /api/public/v2/metricsThe 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.
What you can do
Use the Metrics API to:
- Aggregate cost, token usage, volume, latency, and score data.
- Group results by supported dimensions, such as model, trace name, trace release, or trace version.
- Filter data and analyze trends over time.
- Power custom reports, dashboards, billing, and monitoring workflows.
For supported views, fields, query parameters, response schemas, and interactive examples, see the v2 Metrics API Reference. For practical Python examples, see the Metrics API v2 cookbook.
Data availability: Data from older SDKs (langfuse-python < 4.7.0, langfuse-js < 5.4.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. Details: Versions & Compatibility.
On self-hosted Langfuse v3, use the Metrics API v1 instead; see the self-hosted compatibility matrix.
The Metrics API provides significant performance improvements through an optimized data architecture built on the wide observations table, which minimizes database work per query.
Available Views in v2
| View | Description |
|---|---|
observations | Query observation-level data with optional trace-level aggregations |
scores-numeric | Query numeric scores |
scores-categorical | Query categorical (string) scores |
scores-boolean | Query boolean scores; group or filter by booleanValue, or average value for the true rate |
Key Changes from v1
The deprecated GET /api/public/metrics and GET /api/public/metrics/daily endpoints are documented, with migration steps, in Migration of deprecated APIs.
The traces view is no longer available in v2. Instead, use the observations view which is both faster and more powerful compared to v1.
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/metricsLast edited
