文档 / Metrics API

Metrics API

GET /api/public/v2/metrics

Metrics API 让你能够从 Langfuse 数据中检索定制化的分析。该端点允许你指定维度、指标、过滤器和时间粒度,为你的 LLM 应用构建强大的自定义报表和仪表盘。

已弃用的 GET /api/public/metrics 和 GET /api/public/metrics/daily 端点,连同迁移步骤,记录在已弃用 API 的迁移中。

Metrics API v2

Metrics API v2 在所有 Langfuse Cloud 计划中可用;自托管版本需要 v4。

在自托管 Langfuse v3 上,请改用 Metrics API v1;参见自托管兼容性矩阵。

GET /api/public/v2/metrics

v2 Metrics API 通过基于新事件表 schema 的优化数据架构,提供了显著的性能提升,该架构最小化了每次查询的数据库工作量。

相对 v1 的关键变化

traces 视图在 v2 中不再可用。 请改用 observations 视图,它相比 v1 更快、更强大。

v2 中可用的视图

视图	描述
`observations`	查询 observation 级数据,可选 trace 级聚合
`scores-numeric`	查询数值分数
`scores-categorical`	查询分类(字符串)分数
`scores-boolean`	查询布尔分数;按 `booleanValue` 分组或过滤,或对 `value` 求平均得到 true 比率

行限制

v2 Metrics API 对每次查询强制默认 config.row_limit 为 100 行,以确保一致的性能。你可以在查询中指定自定义 config.row_limit 以覆盖此默认值,最多 1,000 行。

高基数维度

某些维度,如 id、traceId、userId 和 sessionId,不能在 v2 Metrics API 中用于分组。按这些高基数字段分组极其昂贵,且在实践中很少有用。这些维度仍可用于过滤。

按指标排序

按聚合指标排序时,使用格式为 _ 的返回指标字段名,例如用 sum_totalCost 对应 ``。按时间维度排序时,使用返回的字段名 time_dimension。

示例:observations 中使用最贵的模型

bash

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  -G \
  --data-urlencode 'query={
    "view": "observations",
    "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
    "dimensions": [{"field": "providedModelName"}],
    "filters": [],
    "fromTimestamp": "2025-12-01T00:00:00Z",
    "toTimestamp": "2025-12-16T00:00:00Z",
    "orderBy": [{"field": "sum_totalCost", "direction": "desc"}],
    "config": {"row_limit": 1000}
  }' \
  https://cloud.langfuse.com/api/public/v2/metrics

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