Observations API

Observations API 让你可以从 Litefuse 获取 observation 数据（spans、generations、events），用于自定义工作流、评估流水线和分析。

如果你需要的是聚合指标（例如按用户、模型或时间段分组的总成本、token 数或 trace 数量），而不是单个 observation，那么 Metrics API 就是为此设计的，无需自行抓取并聚合原始数据。

关于 API 认证、base URL 和 SDK 访问的通用信息，请参阅 Public API 文档。

Observations API v2

⚠️

仅限 Cloud： v2 Observations API 目前仅在 Litefuse Cloud 可用。我们正在为自托管部署制定可靠的迁移路径。

数据可用性说明： 当使用当前的 SDK 版本时，数据可能需要约 5 分钟才能在 v2 端点上出现。我们即将发布更新的 SDK 版本，届时数据将立即可用。

GET /api/public/v2/observations

v2 Observations API 是一个为高性能数据获取重新设计的端点。它通过最小化 Litefuse 在每次查询中需要执行的工作，解决了 v1 API 的性能瓶颈。

关键改进

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、costDetails、totalCost
`prompt`	promptId、promptName、promptVersion
`metrics`	latency、timeToFirstToken

如果未指定 fields，默认返回 core 与 basic 字段组。

2. 基于 cursor 的分页

v1 API 使用基于偏移量的分页（页码），在大数据集下会变得越来越慢。v2 API 使用基于 cursor 的分页，性能更好且更稳定。

工作原理：

在初次请求中带上 limit 参数
如果还有更多结果，响应的 meta 对象中会包含一个 cursor
在下一次请求中通过 cursor 参数传入此 cursor，从上次结束的位置继续
重复直到不再返回 cursor（你已读到末尾）

结果始终按 startTime 降序排序（最新优先）。

带 cursor 的响应示例：

{
  "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）时，说明你已经获取了全部匹配的 observation。

3. 优化的 I/O 处理

v1 API 总是尝试将 input/output 解析为 JSON，开销可能较大。v2 API 默认将 I/O 作为字符串返回。仅在你需要解析后的 JSON 时才设置 parseIoAsJson: true。

4. 更严格的限制

特性	v1	v2
默认 limit	1000	50
最大 limit	无限制	1,000

常见用例

轮询最近的 observation：

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

获取特定 trace 的 observation：

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

对结果分页：

# 第一次请求
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://litefuse.cloud/api/public/v2/observations?fromStartTime=2025-12-01T00:00:00Z&limit=100"
 
# 响应中包含: "meta": { "cursor": "eyJsYXN0..." }
 
# 带 cursor 的下一次请求
curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  "https://litefuse.cloud/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 编码 cursor（来自上一次响应）
`fromStartTime`	datetime	获取 startTime 大于等于该时间的 observation
`toStartTime`	datetime	获取 startTime 早于该时间的 observation
`traceId`	string	按 trace ID 过滤
`name`	string	按 observation 名称过滤
`type`	string	按 observation 类型过滤（GENERATION、SPAN、EVENT）
`userId`	string	按 user ID 过滤
`level`	string	按日志级别过滤（DEBUG、DEFAULT、WARNING、ERROR）
`parentObservationId`	string	按父 observation ID 过滤
`environment`	string	按环境过滤
`version`	string	按版本 tag 过滤
`parseIoAsJson`	boolean	将 input/output 解析为 JSON（默认：false）
`filter`	string	过滤条件的 JSON 数组（优先级高于 query 参数）

响应示例

包含全部字段时：

{
    "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",
            "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": {},
            "model": "gpt-4o",
            "internalModelId": "",
            "modelParameters": {
                "temperature": 0.2
            },
            "usageDetails": {
                "input": 98,
                "output": 68,
                "total": 166
            },
            "inputUsage": 98,
            "outputUsage": 68,
            "totalUsage": 166,
            "costDetails": {
                "input": 0.000196,
                "output": 0.000204,
                "total": 0.00083
            },
            "inputCost": 0.000196,
            "outputCost": 0.000204,
            "totalCost": 0.00083,
            "promptId": "",
            "promptName": "",
            "promptVersion": null,
            "latency": 0.581,
            "timeToFirstToken": 0.12,
            "userId": "",
            "sessionId": "support-chat-session",
            "modelId": null,
            "inputPrice": null,
            "outputPrice": null,
            "totalPrice": null
        }
    ],
    "meta": {
        "cursor": "eyJsYXN0U3RhcnRUaW1lVG8iOiIyMDI1LTEyLTE3VDE2OjA5OjAwLjg3NVoiLCJsYXN0VHJhY2VJZCI6InN1cHBvcnQtY2hhdC03LTk1MGRjNTNhIiwibGFzdElkIjoic3VwcG9ydC1jaGF0LTctOTUwZGM1M2EtZ2VuIn0="
    }
}

API Reference： 查看完整的 v2 Observations API Reference，了解所有可用参数、响应 schema 与交互式示例。

Observations API v1

GET /api/public/observations

v1 Observations API 仍然为已有集成保留。对于新的实现，我们推荐使用 v2 API 以获得更好的性能。

v1 文档请参阅 API Reference。

MCP Server Public API

这个页面对你有帮助吗？

支持