DocsProduction AnalyticsMetrics API

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:

ParameterTypeDescription
queryJSON stringThe encoded query object defining what metrics to retrieve

Query Object Structure

FieldTypeRequiredDescription
viewstringYesThe data view to query: "traces", "observations", "scores-numeric", or "scores-categorical"
dimensionsarrayNoArray of dimension objects to group by, e.g. [{ "field": "name" }]
metricsarrayYesArray of metric objects to calculate, e.g. [{ "measure": "latency", "aggregation": "p95" }]
filtersarrayNoArray of filter objects to narrow results, e.g. [{ "column": "metadata", "operator": "contains", "key": "customKey", "value": "customValue", "type": "stringObject" }]
timeDimensionobjectNoConfiguration for time-based analysis, e.g. { "granularity": "day" }
fromTimestampstringYesISO timestamp for the start of the query period
toTimestampstringYesISO timestamp for the end of the query period
orderByarrayNoSpecification 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

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

ViewDescription
tracesQuery data at the trace level
observationsQuery data at the observation level
scores-numericQuery numeric and boolean scores
scores-categoricalQuery categorical (string) scores

Trace Dimensions

DimensionTypeDescription
idstringTrace ID
namestringTrace name
tagsstring[]Trace tags
userIdstringUser ID associated with the trace
sessionIdstringSession ID associated with the trace
releasestringRelease tag
versionstringVersion tag
environmentstringEnvironment (e.g., production, staging)
observationNamestringName of related observations
scoreNamestringName of related scores

Trace Metrics

MetricDescription
countCount of traces
observationsCountCount of observations within traces
scoresCountCount of scores within traces
latencyTrace duration in milliseconds
totalTokensTotal tokens used in the trace
totalCostTotal cost of the trace

Observation Dimensions

DimensionTypeDescription
idstringObservation ID
traceIdstringAssociated trace ID
traceNamestringName of the parent trace
environmentstringEnvironment (e.g., production, staging)
parentObservationIdstringID of parent observation
typestringObservation type
namestringObservation name
levelstringLog level
versionstringVersion
providedModelNamestringModel name
promptNamestringPrompt name
promptVersionstringPrompt version
userIdstringUser ID from parent trace
sessionIdstringSession ID from parent trace
traceReleasestringRelease from parent trace
traceVersionstringVersion from parent trace
scoreNamestringRelated score name

Observation Metrics

MetricDescription
countCount of observations
latencyObservation duration in milliseconds
totalTokensTotal tokens used
totalCostTotal cost
timeToFirstTokenTime to first token in milliseconds
countScoresCount of related scores

Score Dimensions (Common)

DimensionTypeDescription
idstringScore ID
namestringScore name
environmentstringEnvironment
sourcestringScore source
dataTypestringData type
traceIdstringRelated trace ID
traceNamestringRelated trace name
userIdstringUser ID from trace
sessionIdstringSession ID from trace
observationIdstringRelated observation ID
observationNamestringRelated observation name
observationModelNamestringModel used in related observation
observationPromptNamestringPrompt name used in related observation
observationPromptVersionstringPrompt version used in related observation
configIdstringConfiguration ID

Score Metrics

Numeric Scores

MetricDescription
countCount of scores
valueNumeric score value

Categorical Scores

MetricDescription
countCount of scores

Categorical scores have an additional dimension:

DimensionTypeDescription
stringValuestringString value of the categorical score

Daily Metrics API (Legacy)

⚠️

This API is a legacy API. For new use cases, please use the Metrics API instead. 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.

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

Was this page useful?

Questions? We're here to help

Subscribe to updates