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.

Overview

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

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