学习笔记 · Obsidian
Run v2 查询、投影、共享与公开 Trace
v2 Run API 是面向大规模 tracing 查询的新契约：以时间窗口限制扫描，用不透明 cursor 翻页，用 selects 精确投影字段。官方明确 self-hosted 需 LangSmith v0.16+。
端点地图
| 能力 | 方法与路径 | 核心参数 |
|---|---|---|
| 读单 Run | GET /api/v2/runs/{run_id} | 必填 project_id；start_time可加速；selects |
| 得到 UI URL | GET /api/v2/runs/{run_id}/url | 必填 project_id + trace_id；start_time 可选 |
| 查 Trace 内 Runs | GET /api/v2/traces/{trace_id}/runs | project_id、filter、成对的 min/max time、selects |
| 分页查 Runs | POST /api/v2/runs/query | 项目/数据集作用域、时间窗、filter、cursor、selects |
| 分页查 Traces | POST /api/v2/traces/query | 单 project、根/树 filter、cursor、selects |
| 共享 | POST /api/v2/runs/{run_id}/share | body 中 session_id、trace_id |
| 取消共享 | DELETE /api/v2/runs/{trace_id}/share | body 中 session_id；幂等 204 |
| 公开读单 Run | GET /api/v2/public/{share_token}/run/{run_id} | 必填精确 start_time 与可重复 selects |
| 公开查 Trace | POST /api/v2/public/{share_token}/runs/query | body 中公开字段 selects |
时间窗、作用域和分页
POST /runs/query 中 project_ids 与 reference_dataset_id 二选一；默认扫描从 1 天前到现在。page_size 默认 100，允许 1–1000。响应的 items 按 start_time 降序，next_cursor 是不透明值；只能原样回传，不解码、不修改、不跨查询条件复用。
POST /traces/query 只查一个 project_id，默认最近 24 小时，page_size 默认 20、上限 100。每个 item 已将根 Run 和 total_tokens|total_cost|first_token_time 等 trace aggregate 放在不同子对象，客户端不需再按 trace_id 二次聚合。
GET /traces/{trace_id}/runs 的 min_start_time 和 max_start_time 要同时提供，且边界 inclusive。时间一律使用 RFC3339/UTC，持久化原始 cursor 时还应一起保存查询条件和时间窗，避免重启后漏读/重读。
三种 filter 不可混淆
filter：对当前返回的每个 Run 求值；trace_filter：对 Trace 的根 Run 求值；tree_filter：只要 Run 树中任意节点匹配就命中。
trace_ids 是已知 ID 集合的快路径，比把大量 ID 拼进 filter 更适合规模化查询。对用户输入的 filter 先走语法验证，再加时间/项目作用域和服务端限额，防止无界扫描。
字段投影与数据最小化
selects 省略时只返回 id。可选字段包括时间/延迟、错误、inputs/outputs/events/extra/manifest、树关系、tokens/cost 及明细、attachments、feedback stats 和 share URL。列表页应先取 preview/指标，点进详情再取载荷；不要默认下载输入输出、事件和预签名附件 URL。
分享是 capability，不是普通资源 ID
受保护的 v2 端点要求 tenant 上下文，并在 API 密钥或 Bearer 认证中二选一。公开端点没有额外认证；URL 中的随机分享凭据本身就承担访问授权。子 Run 的 share 会共享整个 Trace 根；共享前必须对整树做 PII/密钥/客户数据检查。
Share 响应给 share_token；带 SHARE_URL 投影时可返回稳定公开 URL，取消共享前任何拿到 URL 的人都可匿名读取。不把 token/URL 写入日志、Trace、分析埋点或客服截图。Unshare 无论 token 是否存在都返回 204，适合幂等撤销；仍应记录审计事件并检查 CDN/下游缓存策略。
错误处理
v2 明确区分 400、401、403、404、422、500、501、503、504。不应将 404 解释为纯粹“不存在”，它也可能是项目不属于 workspace 或越权隐藏；501 表示 self-hosted 没有 v2 backend/回退能力，应做版本门禁而不是无限重试。只对幂等读取的网络错误、503/504 做有界退避。