文档 / Observations API

Observations API

Observations API 让你能够从 Langfuse 检索 observation 数据(spans、generations、events),用于自定义工作流、评估流水线和分析。

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

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

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

Observations API v2

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

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

GET /api/public/v2/observations

v2 Observations API 是一个为高性能数据检索而重新设计的端点。它通过最小化 Langfuse 每次查询必须执行的工作,解决了 v1 API 的性能瓶颈。

从旧版 trace 和 observation 读取升级

迁移指南将每个已弃用的读取端点(/api/public/traces、/api/public/observations、/api/public/sessions 等)映射到其 v2 替代品,带参数映射和前后示例。始终包含 fromStartTime 和 toStartTime 以保持每个请求有界。

v2 Observations API 返回 observation 行,而非完整的 trace 对象。当你需要重建 trace 活动时按 traceId 分组行,并使用 Metrics API v2 进行带 trace 级维度(如 traceName、traceRelease 或 traceVersion)的聚合报告。对于单个 observation 查找,在 id 列上传递 URL 编码的 filter 条件;过滤器 schema 参见 v2 Observations API Reference。

关键改进

1. 选择性字段检索

v1 API 返回带所有字段(input/output、usage、metadata 等)的完整行,迫使你只需要子集时数据库也扫描每一列。v2 API 让你以逗号分隔的字符串指定需要哪些字段组:

?fields=core,basic,usage

可用字段组

组	字段
`core`	始终包含:id、traceId、startTime、endTime、projectId、parentObservationId、type
`basic`	name、level、statusMessage、version、environment、bookmarked、public、userId、sessionId
`time`	completionStartTime、createdAt、updatedAt
`io`	input、output
`metadata`	metadata
`model`	providedModelName、internalModelId、modelParameters
`usage`	usageDetails、inputUsage、outputUsage、totalUsage、costDetails、inputCost、outputCost、totalCost、usagePricingTierName
`prompt`	promptId、promptName、promptVersion
`metrics`	latency、timeToFirstToken
`trace_context`	tags、release、traceName

如果未指定 fields,默认返回 core 和 basic 字段组。你未请求的组中的字段在响应中不存在,而非 null。以下字段是例外,始终存在但仅在选择字段组 model 时填充:modelId、inputPrice、outputPrice 和 totalPrice。注意 inputPrice、outputPrice 和 totalPrice 以字符串形式返回(例如 "0.000005")以保留小数精度;在你的流水线中将它们转换为数值类型。

2. 基于游标的分页

v1 API 使用基于偏移的分页(页码),对于大数据集会越来越慢。v2 API 使用基于游标的分页,以获得更好、更一致的性能。

工作原理:

用 limit 参数发出初始请求
如果存在更多结果,响应在 meta 对象中包含一个 cursor
在你的下一个请求中通过 cursor 参数传递此游标,以从你离开的地方继续
重复,直到不返回游标(你已到达末尾)

结果始终按 startTime 降序排序(最新的在前)。

带游标的示例响应:

json

{
  "data": [
    {"id": "obs-1", "traceId": "trace-1", "name": "llm-call", ...},
    {"id": "obs-2", "traceId": "trace-1", "name": "embedding", ...}
  ],
  "meta": {
    "cursor": "eyJsYXN0U3RhcnRUaW1lIjoiMjAyNS0xMi0xNVQxMDozMDowMFoiLCJsYXN0SWQiOiJvYnMtMTAwIn0="
  }
}

当响应在 meta 中没有 cursor(或 meta.cursor 为 null)时,你已检索所有匹配的 observations。

3. 优化的 I/O 处理

v1 API 总是尝试将 input/output 解析为 JSON,这可能很昂贵。v2 API 以原始字符串返回 I/O;当你需要 JSON 时在你的流水线中解析它们。parseIoAsJson 参数已弃用:省略它或将其设置为 false;将其设置为 true 会返回 400 错误。

4. 更高的限制

功能	v1	v2
默认限制	50	50
最大限制	100	1,000

在 Langfuse Cloud 上,对 v2 Observations API 的请求计入通用的每组织 API 速率限制(参见 API 限制 FAQ)。自托管实例没有强制的速率限制。

常见用例

轮询最近的 observations:

bash

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?fromStartTime=2025-12-15T00:00:00Z&toStartTime=2025-12-16T00:00:00Z&limit=10"

获取特定 trace 的 observations:

bash

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?fields=core,basic,usage&traceId=your-trace-id"

分页遍历结果:

bash

# First request
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?fromStartTime=2025-12-01T00:00:00Z&limit=100"

# Response includes: "meta": { "cursor": "eyJsYXN0..." }

# Next request with cursor
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://cloud.langfuse.com/api/public/v2/observations?fromStartTime=2025-12-01T00:00:00Z&limit=100&cursor=eyJsYXN0..."

参数

参数	类型	描述
`fields`	string	要包含的字段组的逗号分隔列表。默认为 `core,basic`
`limit`	integer	每页条目数。默认 50,最大 1,000
`cursor`	string	用于分页的 Base64 编码游标(来自上一个响应)
`fromStartTime`	datetime	检索 startTime 在此日期时间或之后的 observations
`toStartTime`	datetime	检索 startTime 在此日期时间之前的 observations
`traceId`	string	按 trace ID 过滤
`name`	string	按 observation 名称过滤
`type`	string	按 observation 类型过滤(GENERATION、SPAN、EVENT)
`userId`	string	按用户 ID 过滤
`level`	string	按日志级别过滤(DEBUG、DEFAULT、WARNING、ERROR)
`parentObservationId`	string	按父 observation ID 过滤
`environment`	string	按环境过滤
`version`	string	按版本标签过滤
`parseIoAsJson`	boolean	已弃用:省略或设为 `false`;`true` 返回 `400` 错误
`filter`	string	过滤条件的 JSON 数组(优先于查询参数)

示例响应

包含所有字段

json

{
  "data": [
    {
      "id": "support-chat-7-950dc53a-gen",
      "traceId": "support-chat-7-950dc53a",
      "startTime": "2025-12-17T16:09:00.875Z",
      "projectId": "7a88fb47-b4e2-43b8-a06c-a5ce950dc53a",
      "parentObservationId": null,
      "type": "GENERATION",
      "endTime": "2025-12-17T16:09:01.456Z",
      "name": "llm-generation",
      "level": "DEFAULT",
      "statusMessage": "",
      "version": "",
      "environment": "default",
      "bookmarked": false,
      "public": false,
      "completionStartTime": "2025-12-17T16:09:00.995Z",
      "createdAt": "2025-12-17T16:09:00.875Z",
      "updatedAt": "2025-12-17T16:09:01.456Z",
      "input": "{\"messages\":[{\"role\":\"user\",\"content\":\"Perfect.\"}]}",
      "output": "{\"role\":\"assistant\",\"content\":\"You're all set. Have a great day!\"}",
      "metadata": {},
      "providedModelName": "gpt-4o",
      "internalModelId": "clm1a2b3c4d5e6f7g8h9i0j1",
      "modelParameters": {
        "temperature": 0.2
      },
      "usageDetails": {
        "input": 98,
        "output": 68,
        "total": 166
      },
      "inputUsage": 98,
      "outputUsage": 68,
      "totalUsage": 166,
      "costDetails": {
        "input": 0.00049,
        "output": 0.00204,
        "total": 0.00253
      },
      "inputCost": 0.00049,
      "outputCost": 0.00204,
      "totalCost": 0.00253,
      "promptId": "",
      "promptName": "",
      "promptVersion": null,
      "latency": 0.581,
      "timeToFirstToken": 0.12,
      "userId": "",
      "sessionId": "support-chat-session",
      "modelId": "clm1a2b3c4d5e6f7g8h9i0j1",
      "inputPrice": "0.000005",
      "outputPrice": "0.00003",
      "totalPrice": null,
      "usagePricingTierName": null,
      "tags": ["support", "chat"],
      "release": "v1.4.2",
      "traceName": "support-chat"
    }
  ],
  "meta": {
    "cursor": "eyJsYXN0U3RhcnRUaW1lVG8iOiIyMDI1LTEyLTE3VDE2OjA5OjAwLjg3NVoiLCJsYXN0VHJhY2VJZCI6InN1cHBvcnQtY2hhdC03LTk1MGRjNTNhIiwibGFzdElkIjoic3VwcG9ydC1jaGF0LTctOTUwZGM1M2EtZ2VuIn0="
  }
}

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