Metrics API

GET /api/public/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.

Metrics API v2 (Beta)

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

Row Limit

The v2 Metrics API enforces a default rowLimit of 100 rows per query to ensure consistent performance. You can specify a custom rowLimit in your query to override this default.

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.

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

Metrics API v1

The Metrics API supports querying across different views (traces, observations, scores) and allows you to:

• Select specific dimensions to group your data
• Apply multiple metrics with different aggregation methods
• Filter data based on metadata, timestamps, and other properties
• Analyze data across time with customizable granularity
• Order results according to your needs

Query Parameters

The API accepts a JSON query object passed as a URL-encoded parameter:

Query Object Structure

Dimension Object Structure

{ "field": "name" }

Metric Object Structure

{ "measure": "count", "aggregation": "count" }

Common measure types include:

• count - Count of records
• latency - Duration/latency metrics

Aggregation types include:

• sum - Sum of values
• avg - Average of values
• count - Count of records
• max - Maximum value
• min - Minimum value
• p50 - 50th percentile
• p75 - 75th percentile
• p90 - 90th percentile
• p95 - 95th percentile
• p99 - 99th percentile

Filter Object Structure

{
  "column": "metadata",
  "operator": "contains",
  "key": "customKey",
  "value": "customValue",
  "type": "stringObject"
}

Time Dimension Object

{
  "granularity": "day"
}

Supported granularities include: hour, day, week, month, and auto.

Example

Here’s an example of querying the number of traces grouped by name:

curl \
-H "Authorization: Basic <BASIC AUTH HEADER>" \
-G \
--data-urlencode 'query={
  "view": "traces",
  "metrics": [{"measure": "count", "aggregation": "count"}],
  "dimensions": [{"field": "name"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}' \
https://cloud.langfuse.com/api/public/metrics

query = """
{
  "view": "traces",
  "metrics": [{"measure": "count", "aggregation": "count"}],
  "dimensions": [{"field": "name"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""
 
langfuse.api.metrics.metrics(query = query)

Response:

{
  "data": [
    { "name": "trace-test-2", "count_count": "10" },
    { "name": "trace-test-3", "count_count": "5" },
    { "name": "trace-test-1", "count_count": "3" }
  ]
}

Data Model

The Metrics API provides access to several data views, each with its own set of dimensions and metrics you can query. This section outlines the available options for each view.

Available Views

Trace Dimensions

Trace Metrics

Observation Dimensions

Observation Metrics

Score Dimensions (Common)

Score Metrics

Numeric Scores

Categorical Scores

Categorical scores have an additional dimension:

Daily Metrics API (Legacy)

GET /api/public/metrics/daily

Via the Daily Metrics API, you can retrieve aggregated daily usage and cost metrics from Langfuse for downstream use, e.g., in analytics, billing, and rate-limiting. The API allows you to filter by application type, user, or tags for tailored data retrieval.

See API reference for more details.

Overview

Returned data includes daily timeseries of:

• Cost in USD
• Trace and observation count
• Break down by model name
• Usage (e.g. tokens) broken down by input and output usage
• Cost in USD
• Trace and observation count

Optional filters:

• traceName to commonly filter by the application type, depending on how you use name in your traces
• userId to filter by user
• tags to filter by tags
• fromTimestamp
• toTimestamp

Missing a key metric or filter? Request it via our idea board.

Example

GET /api/public/metrics/daily?traceName=my-copilot&userId=john&limit=2

{
  "data": [
    {
      "date": "2024-02-18",
      "countTraces": 1500,
      "countObservations": 3000,
      "totalCost": 102.19,
      "usage": [
        {
          "model": "llama2",
          "inputUsage": 1200,
          "outputUsage": 1300,
          "totalUsage": 2500,
          "countTraces": 1000,
          "countObservations": 2000,
          "totalCost": 50.19
        },
        {
          "model": "gpt-4",
          "inputUsage": 500,
          "outputUsage": 550,
          "totalUsage": 1050,
          "countTraces": 500,
          "countObservations": 1000,
          "totalCost": 52.0
        }
      ]
    },
    {
      "date": "2024-02-17",
      "countTraces": 1250,
      "countObservations": 2500,
      "totalCost": 250.0,
      "usage": [
        {
          "model": "llama2",
          "inputUsage": 1000,
          "outputUsage": 1100,
          "totalUsage": 2100,
          "countTraces": 1250,
          "countObservations": 2500,
          "totalCost": 250.0
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 2,
    "totalItems": 60,
    "totalPages": 30
  }
}