title	Metrics API
sidebarTitle	Metrics API
description	Retrieve custom metrics from Langfuse for flexible analytics and reporting.

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 older Metrics API remains available, but is not recommended as the default for new aggregate data extraction workflows because it is less performant at scale. Use Metrics API v2 for new reporting, billing, dashboard, and monitoring workflows.

Metrics API v2 [#v2]

Cloud-only: The v2 Metrics API is only available on Langfuse Cloud. We are working on a robust migration path for self-hosted deployments.

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 or JS/TS SDK v5, or set that header on your OTEL span exporter, to see new data in real time.

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.

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.

Legacy Metrics API v1 [#v1]

The v1 GET /api/public/metrics endpoint remains available, but is not recommended as the default for new aggregate data extraction workflows because it is less performant at scale. Use Metrics API v2 for new reporting, billing, dashboard, and monitoring workflows.

When moving existing queries to v2:

Replace GET /api/public/metrics with GET /api/public/v2/metrics.
Replace view: "traces" with view: "observations" and use trace-level dimensions such as traceName, traceRelease, or traceVersion where supported. userId and sessionId remain available as filters, but cannot be used for grouping in v2.
Review your metrics array when migrating trace-view queries. In the v2 observations view, measures such as count, latency, totalCost, and totalTokens are calculated over observation rows. Use Observations API v2 and group by traceId client-side when you need trace-level counts or trace durations.
Set config.row_limit explicitly when migrating queries that should return more than the default 100 rows.
Use Observations API v2 instead if you need row-level spans, generations, or events.

The rest of this section documents the legacy v1 endpoint for existing integrations.

The v1 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 v1 API accepts a JSON query object passed as a URL-encoded parameter:

Parameter	Type	Description
`query`	JSON string	The encoded query object defining what metrics to retrieve

Query Object Structure

Field	Type	Required	Description
`view`	string	Yes	The data view to query: `"traces"`, `"observations"`, `"scores-numeric"`, or `"scores-categorical"`
`dimensions`	array	No	Array of dimension objects to group by, e.g. `[{ "field": "name" }]`
`metrics`	array	Yes	Array of metric objects to calculate, e.g. `[{ "measure": "latency", "aggregation": "p95" }]`
`filters`	array	No	Array of filter objects to narrow results, e.g. `[{ "column": "metadata", "operator": "contains", "key": "customKey", "value": "customValue", "type": "stringObject" }]`
`timeDimension`	object	No	Configuration for time-based analysis, e.g. `{ "granularity": "day" }`
`fromTimestamp`	string	Yes	ISO timestamp for the start of the query period
`toTimestamp`	string	Yes	ISO timestamp for the end of the query period
`orderBy`	array	No	Specification for result ordering, e.g. `[{ "field": "name", "direction": "asc" }]`

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.legacy.metrics_v1.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 v1 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

View	Description
`traces`	Query data at the trace level
`observations`	Query data at the observation level
`scores-numeric`	Query numeric and boolean scores
`scores-categorical`	Query categorical (string) scores

Trace Dimensions

Dimension	Type	Description
`id`	string	Trace ID
`name`	string	Trace name
`tags`	string[]	Trace tags
`userId`	string	User ID associated with the trace
`sessionId`	string	Session ID associated with the trace
`release`	string	Release tag
`version`	string	Version tag
`environment`	string	Environment (e.g., production, staging)
`observationName`	string	Name of related observations
`scoreName`	string	Name of related scores

Trace Metrics

Metric	Description
`count`	Count of traces
`observationsCount`	Count of observations within traces
`scoresCount`	Count of scores within traces
`latency`	Trace duration in milliseconds
`totalTokens`	Total tokens used in the trace
`totalCost`	Total cost of the trace

Observation Dimensions

Dimension	Type	Description
`id`	string	Observation ID
`traceId`	string	Associated trace ID
`traceName`	string	Name of the parent trace
`environment`	string	Environment (e.g., production, staging)
`parentObservationId`	string	ID of parent observation
`type`	string	Observation type
`name`	string	Observation name
`level`	string	Log level
`version`	string	Version
`providedModelName`	string	Model name
`promptName`	string	Prompt name
`promptVersion`	string	Prompt version
`userId`	string	User ID from parent trace
`sessionId`	string	Session ID from parent trace
`traceRelease`	string	Release from parent trace
`traceVersion`	string	Version from parent trace
`scoreName`	string	Related score name

Observation Metrics

Metric	Description
`count`	Count of observations
`latency`	Observation duration in milliseconds
`totalTokens`	Total tokens used
`totalCost`	Total cost
`timeToFirstToken`	Time to first token in milliseconds
`countScores`	Count of related scores

Score Dimensions (Common)

Dimension	Type	Description
`id`	string	Score ID
`name`	string	Score name
`environment`	string	Environment
`source`	string	Score source
`dataType`	string	Data type
`traceId`	string	Related trace ID
`traceName`	string	Related trace name
`userId`	string	User ID from trace
`sessionId`	string	Session ID from trace
`observationId`	string	Related observation ID
`observationName`	string	Related observation name
`observationModelName`	string	Model used in related observation
`observationPromptName`	string	Prompt name used in related observation
`observationPromptVersion`	string	Prompt version used in related observation
`configId`	string	Configuration ID

Score Metrics

Numeric Scores

Metric	Description
`count`	Count of scores
`value`	Numeric score value

Categorical Scores

Metric	Description
`count`	Count of scores

Categorical scores have an additional dimension:

Dimension	Type	Description
`stringValue`	string	String value of the categorical score

Daily Metrics API (Legacy) [#daily-metrics]

This endpoint is legacy and is no longer listed in the public API reference. It remains available for backward compatibility, but for new use cases please use the Metrics API v2 above. It has higher rate limits and offers more flexibility.

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.

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
  }
}

Navigation Menu

Uh oh!

Metrics API

Metrics API v2 [#v2]

Key Changes from v1

Available Views in v2

Row Limit

High Cardinality Dimensions

Ordering by metrics

Example: Most expensive models used in observations

Legacy Metrics API v1 [#v1]

Query Parameters

Query Object Structure

Dimension Object Structure

Metric Object Structure

Filter Object Structure

Time Dimension Object

Example

Data Model

Available Views

Trace Dimensions

Trace Metrics

Observation Dimensions

Observation Metrics

Score Dimensions (Common)

Score Metrics

Numeric Scores

Categorical Scores

Daily Metrics API (Legacy) [#daily-metrics]

Overview

Example

Uh oh!

FilesExpand file tree

metrics-api.mdx

Latest commit

History

metrics-api.mdx

File metadata and controls

Metrics API

Metrics API v2 [#v2]

Key Changes from v1

Available Views in v2

Row Limit

High Cardinality Dimensions

Ordering by metrics

Example: Most expensive models used in observations

Legacy Metrics API v1 [#v1]

Query Parameters

Query Object Structure

Dimension Object Structure

Metric Object Structure

Filter Object Structure

Time Dimension Object

Example

Data Model

Available Views

Trace Dimensions

Trace Metrics

Observation Dimensions

Observation Metrics

Score Dimensions (Common)

Score Metrics

Numeric Scores

Categorical Scores

Daily Metrics API (Legacy) [#daily-metrics]

Overview

Example