Implementation:Langfuse Langfuse API Metrics V2 Schema

Knowledge Sources	Langfuse Langfuse API Reference
Domains	API, Metrics
Last Updated	2026-02-14 00:00 GMT

Overview

Fern API definition for the v2 metrics API, providing an optimized query interface for retrieving aggregated metrics from observations and scores with flexible dimensions, filters, and time grouping.

Description

This file defines the public API contract for the v2 metrics endpoint at GET /api/public/v2/metrics. This is an enhanced version of the v1 metrics API with optimized performance and refined view support. The endpoint accepts a JSON-encoded query string parameter with the following capabilities:

Supported Views:

• observations -- Query observation-level data (spans, generations, events) with 13 dimensions and 13 measures
• scores-numeric -- Query numeric and boolean score data with 16 dimensions and 2 measures
• scores-categorical -- Query categorical score data (same dimensions as scores-numeric, uses stringValue instead of value)

Key V2 Differences from V1:

• Does not support the traces view (available only in v1)
• Direct access to tags and release fields on observations
• Backwards-compatible traceName, traceRelease, traceVersion dimensions still available
• High cardinality dimensions are blocked as grouping dimensions (must use filters instead)

Aggregation Functions: sum, avg, count, max, min, p50, p75, p90, p95, p99, histogram

Time Granularities: auto, minute, hour, day, week, month

Usage

Developers reference this definition when:

• Building custom dashboards or analytics integrations
• Generating SDK types for the metrics query API
• Understanding available dimensions and measures per view
• Migrating from v1 to v2 metrics API

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/server/definition/metrics-v2.yml
• Lines: 1-178

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    metrics:
      docs: Get metrics from the Langfuse project using a query object.
            V2 endpoint with optimized performance.
      method: GET
      path: /v2/metrics
      request:
        name: GetMetricsV2Request
        query-parameters:
          query:
            type: string
            docs: JSON string containing the query parameters
      response: MetricsV2Response

types:
  MetricsV2Response:
    properties:
      data:
        type: list<map<string, unknown>>
        docs: The metrics data. Each item in the list contains the metric
              values and dimensions requested in the query.

I/O Contract

Endpoints

Method	Path	Description
GET	/api/public/v2/metrics	Query aggregated metrics with flexible dimensions, measures, filters, and time grouping

Query Parameters

The query parameter is a JSON string with the following structure:

Field	Type	Required	Description
view	string	Yes	One of: "observations", "scores-numeric", "scores-categorical"
dimensions	array	No	Fields to group by (e.g., [{"field": "name"}])
metrics	array	Yes	Measures and aggregations (e.g., [{"measure": "count", "aggregation": "sum"}])
filters	array	No	Filter conditions with column, operator, value, and type
timeDimension	object	No	Time grouping with granularity (auto, minute, hour, day, week, month)
fromTimestamp	string	Yes	ISO datetime start of time range
toTimestamp	string	Yes	ISO datetime end of time range
orderBy	array	No	Ordering by field and direction (asc/desc)
config	object	No	bins (1-100, default 10) and row_limit (1-1000, default 100)

Key Types

Type Name	Description
MetricsV2Response	Contains a data array of maps where keys and values depend on the query dimensions and metrics

Observations View Dimensions and Measures

Dimensions	Measures
environment, type, name, level, version, tags, release, traceName, traceRelease, traceVersion, providedModelName, promptName, promptVersion, startTimeMonth	count, latency, streamingLatency, inputTokens, outputTokens, totalTokens, outputTokensPerSecond, tokensPerSecond, inputCost, outputCost, totalCost, timeToFirstToken, countScores

Usage Examples

# Query observation count grouped by name
curl -X GET "https://cloud.langfuse.com/api/public/v2/metrics?query=%7B%22view%22%3A%22observations%22%2C%22dimensions%22%3A%5B%7B%22field%22%3A%22name%22%7D%5D%2C%22metrics%22%3A%5B%7B%22measure%22%3A%22count%22%2C%22aggregation%22%3A%22sum%22%7D%5D%2C%22fromTimestamp%22%3A%222026-02-01T00%3A00%3A00Z%22%2C%22toTimestamp%22%3A%222026-02-14T00%3A00%3A00Z%22%7D" \
  -H "Authorization: Bearer $API_KEY"

# Decoded query:
# {
#   "view": "observations",
#   "dimensions": [{"field": "name"}],
#   "metrics": [{"measure": "count", "aggregation": "sum"}],
#   "fromTimestamp": "2026-02-01T00:00:00Z",
#   "toTimestamp": "2026-02-14T00:00:00Z"
# }

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime