Implementation:Langfuse Langfuse API Metrics Schema

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

Overview

Fern API definition for the v1 metrics API, providing a flexible query interface for retrieving aggregated metrics from traces, observations, and scores.

Description

This file defines the public API contract for the v1 metrics endpoint at GET /api/public/metrics. The endpoint accepts a JSON-encoded query string parameter and returns aggregated metric data. Unlike the v2 endpoint, this version supports the traces view in addition to observations, scores-numeric, and scores-categorical.

The query structure supports:

• Views: traces, observations, scores-numeric, scores-categorical
• Dimensions: Fields to group by (e.g., name, userId, sessionId)
• Metrics: Measures with aggregation functions (count, sum, avg, p95, histogram, etc.)
• Filters: Column-based filtering with operators for datetime, string, number, and boolean types
• Time Dimension: Grouping by time with granularity options (minute, hour, day, week, month, auto)
• Configuration: Optional bins for histograms and row limits

The documentation recommends users consider the v2 endpoint for better performance.

Usage

Developers reference this definition when:

• Maintaining backward compatibility with existing metrics API consumers
• Querying trace-level metrics (not available in v2)
• Generating SDK types for the v1 metrics query interface
• Understanding the full metrics query language and filter options

Code Reference

Source Location

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

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    metrics:
      docs: Get metrics from the Langfuse project using a query object.
            Consider using the v2 metrics endpoint for better performance.
      method: GET
      path: /metrics
      request:
        name: GetMetricsRequest
        query-parameters:
          query:
            type: string
            docs: JSON string containing the query parameters
      response: MetricsResponse

types:
  MetricsResponse:
    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/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: "traces", "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)

Key Types

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

Usage Examples

# Query trace count grouped by name
curl -X GET "https://cloud.langfuse.com/api/public/metrics?query=%7B%22view%22%3A%22traces%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": "traces",
#   "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