Deprecated APIs

These APIs are deprecated and receive security patches only, no other fixes or new functionality. To migrate, see Migration of deprecated APIs.

Deprecated endpoints

All paths are relative to /api/public.

Deprecated endpoint(s)	Parameters	Replacement
`GET /traces`, `/traces/{id}`	API reference	Observations API v2, filtered by `traceId`
`GET /observations`, `/observations/{id}`	API reference	Observations API v2
`GET /sessions`, `/sessions/{id}`	API reference	Observations API v2, filtered by `sessionId`
`GET /scores`, `/v2/scores` (+ `/{id}`)	API reference	Scores API v3
`GET /metrics`	Documented below	Metrics API v2
`GET /metrics/daily`	Documented below	Metrics API v2
`GET /datasets/{name}/runs` (+ `/{runName}`)	API reference	Experiments API
`POST /ingestion`	API reference	OpenTelemetry ingestion
`POST /traces`, `/spans`, `/generations`, `/events`	Not in the API reference	OpenTelemetry ingestion

Score writes via POST /scores are not deprecated.

Metrics API v1

GET /api/public/metrics

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

Replacement: Metrics API v2.

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"`, `"scores-categorical"`, or `"scores-boolean"`
`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 scores
`scores-categorical`	Query categorical (string) scores
`scores-boolean`	Query boolean 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

Boolean Scores

Metric	Description
`count`	Count of scores
`value`	Numeric score value, where `0` is false and `1` is true. Use the `avg` aggregation to return the true rate

Boolean scores have an additional dimension:

Dimension	Type	Description
`booleanValue`	boolean	Boolean value of the score for grouping and filtering

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

GET /api/public/metrics/daily

The Daily Metrics API returns aggregated daily usage and cost metrics for downstream use in analytics, billing, and rate limiting. Filter by trace name, user, or tags.

Replacement: Metrics API v2 with a daily time dimension.

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

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

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 helpful?

On this page