How to Retrieve Experiment Scores?

Terminology Note: "Experiment" and "dataset run" are used interchangeably throughout Langfuse. We are moving toward deprecating the term "dataset run" in favor of "experiment", but both terms currently refer to the same concept.

Langfuse supports two types of experiment scores:

Experiment-level scores: Overall metrics for the entire experiment run (e.g., precision, recall, F1-scores). These scores are immutable and represent aggregate performance. Learn more about run-level scores.
Experiment-item-level scores: Scores for individual items within an experiment (e.g., per-generated-output evaluations).

Via API/SDK

Use the Experiments API to retrieve both score levels. Include fields=scores when listing experiments for experiment-level scores or experiment items for item- and trace-level scores. Both endpoints require fromStartTime and use cursor-based pagination.

from datetime import datetime, timezone
from langfuse import Langfuse

langfuse = Langfuse()
from_start = datetime(2026, 1, 1, tzinfo=timezone.utc)

# Find the experiment and include its scores
experiments = langfuse.api.experiments.list(
    from_start_time=from_start,
    name="your-experiment-name",
    fields="core,scores",
)
experiment = experiments.data[0]

# Fetch its items and include item and trace scores
items = langfuse.api.experiments.list_items(
    from_start_time=from_start,
    experiment_id=experiment.id,
    fields="core,io,scores",
)

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();
const fromStartTime = "2026-01-01T00:00:00Z";

// Find the experiment and include its scores
const experiments = await langfuse.api.experiments.list({
  fromStartTime,
  name: "your-experiment-name",
  fields: "core,scores",
});
const experiment = experiments.data[0];

// Fetch its items and include item and trace scores
const items = await langfuse.api.experiments.listItems({
  fromStartTime,
  experimentId: experiment.id,
  fields: "core,io,scores",
});

GET /api/public/experiments?fromStartTime=2026-01-01T00:00:00Z&name=your-experiment-name&fields=core,scores
GET /api/public/experiment-items?fromStartTime=2026-01-01T00:00:00Z&experimentId=<experiment-id>&fields=core,io,scores

Recommended: Use Experiment Runner SDK

For a better developer experience, use the Experiment Runner SDK which provides built-in access to all experiment scores and results:

from langfuse import get_client

langfuse = get_client()

# Run experiment with automatic score collection
result = langfuse.run_experiment(
    name="my-experiment",
    data=my_dataset,
    task=my_task,
    evaluators=[my_evaluator]  # optional
)

# Access all scores directly
print(result.format())  # includes all scores in formatted output

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Run experiment with automatic score collection
const result = await langfuse.experiment.run({
  name: "my-experiment",
  data: myDataset,
  task: myTask,
  evaluators: [myEvaluator]  // optional
});

// Access all scores directly
console.log(await result.format());  // includes all scores in formatted output

Was this page helpful?

How to Retrieve Experiment Scores?

Via API/SDK

Recommended: Use Experiment Runner SDK

Related Resources

On this page