文档 / Scores API

Scores API

Scores API 让你能够从 Langfuse 检索分数数据(评估、标注和通过 API 接入的分数),用于自定义工作流、评估流水线和分析。

如果你需要聚合的分数指标(例如按 trace 名称、用户或时间段分组的平均分数)而非单个分数,Metrics API 正是为此设计,并避免了你自己获取和聚合原始数据的需要。

关于 API 身份验证、基础 URL 和 SDK 访问的一般信息,参见 Public API 文档。

本页涵盖读取分数。分数通过 POST /api/public/scores 或 SDK 辅助方法创建;参见通过 API/SDK 打分。已弃用的 GET /api/public/scores 和 GET /api/public/v2/scores 读取端点,连同迁移步骤,记录在已弃用 API 的迁移中。

Scores API v3

Scores API v3 在所有 Langfuse Cloud 计划中可用;自托管版本需要 v3.179。

GET /api/public/v3/scores

响应携带单个类型化的 value 字段,结果用游标分页。

`value` 字段

每个分数携带恰好一个 value。其类型由分数的 dataType 决定:

`dataType`	`value` 类型	备注
`NUMERIC`	number
`BOOLEAN`	boolean
`CATEGORICAL`	string	该类别
`TEXT`	string
`CORRECTION`	string	如果没有修正则为空字符串

如果你的流水线处理混合分数类型,请基于 dataType 分支。

字段组

响应始终包含一个精简核心(id、projectId、name、value、dataType、source、timestamp、environment、createdAt、updatedAt),你通过逗号分隔的 fields 参数选择加入额外的组:

?fields=details,subject,annotation

组	字段
core	始终包含(见上)
`details`	comment、configId、metadata
`subject`	subject(分数所附加的实体,见下)
`annotation`	authorUserId、queueId

未知的组名返回 HTTP 400。

`subject` 对象

每个分数附加到恰好一个实体。请求 subject 字段组以查看是哪一个;它通过 kind 区分:

json

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

kind: "trace":id 是 trace ID
kind: "observation":id 是 observation ID;包含父 traceId
kind: "session":id 是 session ID
kind: "experiment":id 是 dataset run ID

基于游标的分页

用 limit 参数发出初始请求(默认 50,最大 100)
如果存在更多结果,响应在 meta 对象中包含一个 cursor
在你的下一个请求中通过 cursor 参数传递此游标,重复与初始请求相同的过滤参数(游标仅编码读取位置,而非你的查询)
重复,直到不返回游标(你已到达末尾)

对于到你数据仓库的重复完整导出,请使用计划的 blob 存储导出,而非通过 API 分页。

过滤

多值过滤器: 大多数过滤器接受逗号分隔的列表:id、name、source、dataType、environment、configId、queueId、authorUserId、traceId、sessionId、observationId、experimentId。一个参数内的值是 OR 关系,参数之间是 AND 关系:name=hallucination,toxicity&source=EVAL 返回名为 hallucination 或 toxicity 的 eval 分数。
值过滤器: 用 value 进行精确匹配(逗号分隔,需要单个 dataType 为 NUMERIC、BOOLEAN 或 CATEGORICAL),或用 valueMin/valueMax 进行包含性数值范围边界(需要 dataType=NUMERIC)。
互斥性: traceId、sessionId 和 experimentId 互斥。observationId 需要 traceId,因为 observation ID 的作用域是某个 trace。
不区分大小写的枚举: source 和 dataType 接受任意大小写(numeric 和 NUMERIC 等价)。
时间戳边界: fromTimestamp 包含,toTimestamp 不包含。

无效的过滤组合会以 HTTP 400 被拒绝,而非被静默忽略。

常见用例

拉取失败的 evals:

bash

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

获取特定 traces 的分数,包括它们附加到什么:

bash

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

按 ID 获取单个分数:

bash

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

分页遍历结果:

bash

# 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 访问

生成的 SDK 客户端直接暴露 v3 端点。分数创建使用单独的 SDK 辅助方法(例如 Python 中的 create_score);此客户端用于读取。

python

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,
)

# v2 (deprecated): langfuse.api.scores.get_many(...)

也可通过 langfuse.async_api.scores_v3.get_many_v3(...) 异步使用。

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

const langfuse = new LangfuseClient();

// v3 (recommended)
const scores = await langfuse.api.scoresV3.getManyV3({
  name: "hallucination,toxicity",
  dataType: "NUMERIC",
  valueMax: 0.5,
  fields: "details,subject",
  limit: 100,
});

// v2 (deprecated): langfuse.api.scores.getMany(...)

参数

参数	类型	描述
`limit`	integer	每页条目数。默认 50,最大 100(更大的值返回 HTTP 400)
`cursor`	string	用于分页的 URL 安全 base64 游标(来自上一个响应)
`fields`	string	除核心外要包含的逗号分隔字段组:`details`、`subject`、`annotation`
`id`	string	逗号分隔的分数 ID 列表
`name`	string	逗号分隔的分数名称列表
`source`	string	逗号分隔的分数来源列表(`API`、`ANNOTATION`、`EVAL`),不区分大小写
`dataType`	string	逗号分隔的数据类型列表(`NUMERIC`、`BOOLEAN`、`CATEGORICAL`、`TEXT`、`CORRECTION`),不区分大小写。与 `value`、`valueMin` 或 `valueMax` 组合时必须为单个值
`environment`	string	逗号分隔的环境列表
`configId`	string	逗号分隔的分数配置 ID 列表
`queueId`	string	逗号分隔的标注队列 ID 列表
`authorUserId`	string	逗号分隔的作者用户 ID 列表
`value`	string	逗号分隔的精确值列表。需要单个 `dataType` 为 `NUMERIC`、`BOOLEAN` 或 `CATEGORICAL`。对于 `BOOLEAN` 传 `true` 或 `false`;对于 `NUMERIC` 每个值必须是有限数
`valueMin`	number	数值的包含性下界。需要 `dataType=NUMERIC`
`valueMax`	number	数值的包含性上界。需要 `dataType=NUMERIC`
`traceId`	string	逗号分隔的 trace ID 列表。与 `sessionId`、`experimentId` 互斥
`sessionId`	string	逗号分隔的 session ID 列表。与 `traceId`、`observationId`、`experimentId` 互斥
`observationId`	string	逗号分隔的 observation ID 列表。需要 `traceId`
`experimentId`	string	逗号分隔的 dataset run ID(实验 ID)列表。与 `traceId`、`sessionId`、`observationId` 互斥
`fromTimestamp`	datetime	分数时间戳的包含性下界
`toTimestamp`	datetime	分数时间戳的不包含性上界

示例响应

带 fields=details,subject,annotation:

json

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

API 参考: 所有可用参数、响应 schema 和交互式示例,参见完整的 v3 Scores API Reference。

Scores API

Scores API v3

value 字段

字段组

subject 对象

基于游标的分页

过滤

常见用例

SDK 访问

参数

示例响应

`value` 字段

`subject` 对象