Migration of deprecated APIs

This page maps every deprecated Langfuse REST endpoint to its replacement, with parameter mappings, semantic differences, and before/after examples. Many of these changes follow from the observations-first data model: traces and observations are no longer separate entities, and reads are consolidated onto fewer, faster endpoints.

If you access the API through the Langfuse SDKs, use the SDK upgrade guides instead: Python v3 to v4 and JS/TS v4 to v5. This page covers direct REST usage only.

Still need the deprecated endpoints? They are documented in the reference section below.

Quick reference

All paths are relative to /api/public.

Observations

Deprecated: GET /observations, GET /observations/{observationId}.

Replacement: GET /v2/observations (reference).

Parameter mapping

Semantic differences

• Responses include only the requested fields groups; fields from groups you did not request are absent, not null. One exception: modelId, inputPrice, outputPrice, and totalPrice are always present but null unless the model field group is requested.
• input/output are returned as raw strings; parse them in your pipeline when you need JSON (v1 parsed them automatically). The parseIoAsJson parameter is deprecated: omit it or set it to false; setting it to true returns a 400 error.
• Pagination is cursor-based: pass meta.cursor from the previous response until no cursor is returned. Results are always sorted by startTime descending.
• When the model group is requested, inputPrice, outputPrice, and totalPrice are returned as strings (e.g. "0.000005") to preserve decimal precision; cast them to a numeric type in your pipeline.

Example

# Before (v1)
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/observations?type=GENERATION&limit=10&page=1"

# After (v2)
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?type=GENERATION&limit=10&fields=core,basic,usage&fromStartTime=2026-07-01T00:00:00Z&toStartTime=2026-07-16T00:00:00Z"

Traces

Deprecated: GET /traces, GET /traces/{traceId}.

Replacement: GET /v2/observations, grouped by traceId on the client side.

Parameter mapping

Request fields=core,basic,trace_context to include the trace-level attributes traceName, tags, and release on each row.

Semantic differences

• The response contains observation rows, not trace objects. Group rows by traceId to reconstruct trace activity.
• v4 has no trace-level input/output. Reconstruct them from the root observation of each trace: the row with parentObservationId == null.
• For trace-level aggregates (counts, costs, latency grouped by traceName, traceRelease, or traceVersion), use the Metrics API v2 instead of fetching and aggregating rows yourself.

Example

# Before (v1): list traces by name
curl -G \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/traces" \
  --data-urlencode "name=support-conversation" \
  --data-urlencode "limit=50"

# After (v2): fetch observation rows filtered by trace name, group by traceId
curl -G \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations" \
  --data-urlencode 'filter=[{"type":"string","column":"traceName","operator":"=","value":"support-conversation"}]' \
  --data-urlencode "fields=core,basic,io,trace_context" \
  --data-urlencode "fromStartTime=2026-07-01T00:00:00Z" \
  --data-urlencode "toStartTime=2026-07-16T00:00:00Z" \
  --data-urlencode "limit=50"

Sessions

Deprecated: GET /sessions, GET /sessions/{sessionId}. On Langfuse v4, these will return 404.

Replacement: GET /v2/observations with a filter condition on the sessionId column, grouped by sessionId on the client side.

Parameter mapping

Semantic differences

• The response contains observation rows; a "session" is the set of rows sharing a sessionId. Group by sessionId (and within a session, by traceId) to reconstruct the session structure.
• Like traces, sessions have no dedicated input/output object in v4. Reconstruct the conversation from the root observations of the traces within the session.
• sessionId is a high-cardinality field: it is available for filtering in the Metrics API v2, but not for grouping.

Example

# Before (v1): fetch one session
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/sessions/chat-session-42"

# After (v2): fetch the session's observation rows
curl -G \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations" \
  --data-urlencode 'filter=[{"type":"string","column":"sessionId","operator":"=","value":"chat-session-42"}]' \
  --data-urlencode "fields=core,basic,io" \
  --data-urlencode "fromStartTime=2026-07-01T00:00:00Z" \
  --data-urlencode "toStartTime=2026-07-16T00:00:00Z"

Metrics

Deprecated: GET /metrics (v1) and GET /metrics/daily.

Replacement: GET /v2/metrics (reference).

Parameter mapping

The query object structure carries over; the key changes are inside the query:

Semantic differences

• The traces view is removed. In the observations view, measures such as count, latency, totalCost, and totalTokens are calculated over observation rows, not traces. When you need trace-level counts or trace durations, use Observations API v2 and group by traceId client-side.
• When ordering by an aggregated metric, use the returned field name in the format {aggregation}_{measure}, e.g. sum_totalCost.

Example

# Before (v1): trace count by name
curl -G \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  --data-urlencode 'query={"view":"traces","metrics":[{"measure":"count","aggregation":"count"}],"dimensions":[{"field":"name"}],"filters":[],"fromTimestamp":"2026-07-01T00:00:00Z","toTimestamp":"2026-07-16T00:00:00Z"}' \
  "https://cloud.langfuse.com/api/public/metrics"

# After (v2): observation count by trace name
curl -G \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  --data-urlencode 'query={"view":"observations","metrics":[{"measure":"count","aggregation":"count"}],"dimensions":[{"field":"traceName"}],"filters":[],"fromTimestamp":"2026-07-01T00:00:00Z","toTimestamp":"2026-07-16T00:00:00Z"}' \
  "https://cloud.langfuse.com/api/public/v2/metrics"

Daily metrics

GET /metrics/daily returned daily cost and usage timeseries broken down by model. Reproduce it with a v2 query using a daily time dimension:

curl -G \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  --data-urlencode 'query={"view":"observations","metrics":[{"measure":"count","aggregation":"count"},{"measure":"totalCost","aggregation":"sum"},{"measure":"totalTokens","aggregation":"sum"}],"dimensions":[{"field":"providedModelName"}],"timeDimension":{"granularity":"day"},"filters":[],"fromTimestamp":"2026-07-01T00:00:00Z","toTimestamp":"2026-07-16T00:00:00Z"}' \
  "https://cloud.langfuse.com/api/public/v2/metrics"

The deprecated endpoint's filters map to v2 filters entries: traceName and userId are available as filter columns; tags filters on trace tags.

Scores

Deprecated: GET /scores (v1), GET /scores/{scoreId}, GET /v2/scores, GET /v2/scores/{scoreId}. On Langfuse v4, these will return 404.

Replacement: GET /v3/scores. See the Scores API v3 announcement for background.

Parameter mapping

Semantic differences

• One typed value field. NUMERIC scores return a number, BOOLEAN scores a boolean, and CATEGORICAL/TEXT/CORRECTION scores a string; no more parallel value/stringValue fields.
• Field groups. Core fields are always returned; request more via fields=details,subject,annotation. The subject group replaces the flat traceId/observationId/sessionId/datasetRunId response fields with one object describing what the score is attached to (kind: trace, observation, session, or experiment).
• Use at most one of the traceId, sessionId, and experimentId filters; they cannot be combined. observationId requires traceId alongside it (observation IDs are scoped to a trace).
• fromTimestamp is inclusive; toTimestamp is exclusive.
• No trace joins. v3 queries scores directly and does not return trace fields (the v2 trace field group is gone). For row-level filtering by trace properties, query the traces API with userId/tags filters first to collect the matching trace IDs, then pass them to v3's comma-separated traceId filter.
• Row counts can differ. v2 silently dropped scores whose referenced trace could not be found (e.g., deleted or never ingested); v3 returns every matching score, so the same query can return more rows on v3.

Example

# Before (v2): numeric scores for a trace
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/scores?traceId=trace-123&dataType=NUMERIC"

# After (v3)
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?traceId=trace-123&dataType=NUMERIC&fields=details,subject"

Dataset runs → Experiments

Deprecated:

• GET /datasets/{datasetName}/runs
• GET /datasets/{datasetName}/runs/{runName}
• GET /dataset-run-items
• DELETE /datasets/{datasetName}/runs/{runName}
• POST /dataset-run-items

"Dataset run" and "experiment" refer to the same concept; Langfuse is standardizing on "experiment" (terminology note).

Read experiment data

Use GET /experiments to list experiments or find one by its dataset ID and name. Use GET /experiment-items?experimentId=<id> to retrieve the items belonging to an experiment.

Parameter mapping

Semantic differences

• Experiments are queried by dataset ID, not name.
• Item inputs, outputs, and expected outputs are behind the fields=io group on GET /experiment-items; scores are behind fields=scores on both endpoints. This replaces the old workaround of fetching each run item's trace to collect scores.

Create experiment data

For Python and JS/TS, use the Experiment runner SDK. It applies the required experiment semantics automatically and is the recommended replacement for POST /dataset-run-items.

For other languages, send experiment traces to POST /otel/v1/traces and apply the required experiment attributes.

Delete experiment data

Langfuse v4 does not provide an endpoint that deletes only an experiment. To delete its tracing data, list the experiment items with GET /experiment-items?fromStartTime=<timestamp>&experimentId=<id>, collect their traceId values, and pass them to DELETE /traces. The trace deletion endpoint is not deprecated.

This is not semantically equivalent to the deprecated endpoint: deleting the traces also deletes their observations and related scores. See Data Deletion for details.

Example

# Before: fetch a dataset run with its items
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/datasets/my-dataset/runs/my-run"

# After: resolve the dataset ID, find the experiment, then list its items
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/datasets/my-dataset"

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/experiments?fromStartTime=2026-07-01T00:00:00Z&datasetId=<dataset-id>&name=my-run&fields=core,scores"

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/experiment-items?fromStartTime=2026-07-01T00:00:00Z&experimentId=<experiment-id>&fields=io,scores"

Ingestion

Deprecated: POST /ingestion (batched event ingestion) and the older synchronous endpoints POST /traces, POST /spans, POST /generations, POST /events.

Replacement: the OpenTelemetry endpoint POST /otel/v1/traces (OTLP/HTTP), or an upgraded SDK (Python v4.7.0+, JS/TS v5.4.0+). Set the x-langfuse-ingestion-version: 4 header on your OTEL span exporter and propagate trace attributes to all observations; see the OpenTelemetry integration guide.

Score writes via POST /scores are unaffected.

Deprecated endpoints

These endpoints are deprecated and receive security patches only, no other fixes or new functionality. All paths are relative to /api/public.

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:

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

Trace Dimensions

Trace Metrics

Observation Dimensions

Observation Metrics

Score Dimensions (Common)

Score Metrics

Numeric Scores

Boolean Scores

Boolean scores have an additional dimension:

Categorical Scores

Categorical scores have an additional dimension:

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, and allows you to:

• Retrieve daily timeseries of cost in USD and trace and observation counts
• Break down usage (e.g. tokens, split by input and output) and cost by model name
• Filter by trace name, user, or tags

Replacement: Metrics API v2 with a daily time dimension.

Query Parameters

All parameters are optional:

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