Scores API

The Scores API allows you to retrieve score data (evaluations, annotations, and API-ingested scores) from Langfuse for use in custom workflows, evaluation pipelines, and analytics.

If you need aggregated score metrics (e.g., average scores grouped by trace name, user, or time period) rather than individual scores, the Metrics API is designed for this and avoids the need to fetch and aggregate raw data yourself.

For general information about API authentication, base URLs, and SDK access, see the Public API documentation.

This page covers reading scores. Scores are created via POST /api/public/scores or the SDK helpers; see scores via API/SDK.

Scores API v3

Where is this feature available?

• Hobby: Available
• Core: Available
• Pro: Available
• Enterprise: Available
• Self Hosted: Langfuse v3.179.0+

GET /api/public/v3/scores

Responses carry a single typed value field, and results are paginated with a cursor.

value Field

Every score carries exactly one value. Its type is determined by the score's dataType:

If your pipeline handles mixed score types, branch on dataType.

Field Groups

Responses always include a lean core (id, projectId, name, value, dataType, source, timestamp, environment, createdAt, updatedAt), and you opt into additional groups via a comma-separated fields parameter:

?fields=details,subject,annotation

Unknown group names return HTTP 400.

subject Object

Every score is attached to exactly one entity. Request the subject field group to see which one; it is discriminated by kind:

{ "kind": "observation", "id": "obs-1", "traceId": "trace-1" }

• kind: "trace": id is the trace ID
• kind: "observation": id is the observation ID; includes the parent traceId
• kind: "session": id is the session ID
• kind: "experiment": id is the dataset run ID

Cursor-Based Pagination

1. Make your initial request with a limit parameter (default 50, max 100)
2. If more results exist, the response includes a cursor in the meta object
3. Pass this cursor via the cursor parameter in your next request, repeating the same filter parameters as the initial request (the cursor encodes only the read position, not your query)
4. Repeat until no cursor is returned (you've reached the end)

For recurring full exports to your data warehouse, use the scheduled blob storage export instead of paginating through the API.

Filtering

• Multi-value filters: most filters accept comma-separated lists: id, name, source, dataType, environment, configId, queueId, authorUserId, traceId, sessionId, observationId, experimentId. Values within one parameter are OR-ed; parameters are AND-ed: name=hallucination,toxicity&source=EVAL returns eval scores named either hallucination or toxicity.
• Value filters: use value for exact matches (comma-separated, requires a single dataType of NUMERIC, BOOLEAN, or CATEGORICAL) or valueMin/valueMax for inclusive numeric range bounds (require dataType=NUMERIC).
• Mutual exclusivity: traceId, sessionId, and experimentId are mutually exclusive. observationId requires traceId because observation IDs are scoped to a trace.
• Case-insensitive enums: source and dataType accept any casing (numeric and NUMERIC are equivalent).
• Timestamp bounds: fromTimestamp is inclusive, toTimestamp is exclusive.

Invalid filter combinations are rejected with HTTP 400 rather than silently ignored.

Common Use Cases

Pulling failing evals:

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?name=hallucination,toxicity&dataType=NUMERIC&valueMax=0.5"

Getting scores for specific traces, including what they are attached to:

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?traceId=trace-1,trace-2&fields=details,subject"

Fetching a single score by ID:

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?id=your-score-id"

Paginating through results:

# First request
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?fromTimestamp=2026-06-01T00:00:00Z&limit=100"

# Response includes: "meta": { "limit": 100, "cursor": "eyJsYXN0..." }

# Next request with cursor
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v3/scores?fromTimestamp=2026-06-01T00:00:00Z&limit=100&cursor=eyJsYXN0..."

SDK Access

The generated SDK clients expose the v3 endpoint directly. Score creation uses separate SDK helpers (e.g. create_score in Python); this client is for reads.

Python SDK:

from langfuse import get_client

langfuse = get_client()

# v3 (recommended)
scores = langfuse.api.scores_v3.get_many_v3(
    name="hallucination,toxicity",
    data_type="NUMERIC",
    value_max=0.5,
    fields="details,subject",
    limit=100,
)

Also available as async via langfuse.async_api.scores_v3.get_many_v3(...).

Parameters

Sample Response

With fields=details,subject,annotation:

{
  "data": [
    {
      "id": "score-1",
      "projectId": "7a88fb47-b4e2-43b8-a06c-a5ce950dc53a",
      "name": "hallucination",
      "value": 0.25,
      "dataType": "NUMERIC",
      "source": "EVAL",
      "timestamp": "2026-06-15T10:30:00Z",
      "environment": "default",
      "createdAt": "2026-06-15T10:30:01Z",
      "updatedAt": "2026-06-15T10:30:01Z",
      "comment": "Low hallucination risk",
      "configId": null,
      "metadata": {},
      "authorUserId": null,
      "queueId": null,
      "subject": {
        "kind": "observation",
        "id": "support-chat-7-950dc53a-gen",
        "traceId": "support-chat-7-950dc53a"
      }
    },
    {
      "id": "score-2",
      "projectId": "7a88fb47-b4e2-43b8-a06c-a5ce950dc53a",
      "name": "helpful",
      "value": true,
      "dataType": "BOOLEAN",
      "source": "ANNOTATION",
      "timestamp": "2026-06-15T11:00:00Z",
      "environment": "default",
      "createdAt": "2026-06-15T11:00:02Z",
      "updatedAt": "2026-06-15T11:00:02Z",
      "comment": null,
      "configId": "cfg-1",
      "metadata": {},
      "authorUserId": "user-123",
      "queueId": "queue-1",
      "subject": {
        "kind": "trace",
        "id": "support-chat-7-950dc53a"
      }
    }
  ],
  "meta": {
    "limit": 50,
    "cursor": "eyJ2IjoxLCJsYXN0VGltZXN0YW1wIjoiMjAyNi0wNi0xNVQxMTowMDowMFoiLCJsYXN0SWQiOiJzY29yZS0yIn0"
  }
}