---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - tracing
  - query
  - sharing
topic: LangSmith Smith API Run v2 查询、投影、共享与公开 Trace
sources:
  - https://docs.langchain.com/langsmith/smith-api/runs/get-a-public-shared-trace-run
  - https://docs.langchain.com/langsmith/smith-api/runs/get-a-single-run
  - https://docs.langchain.com/langsmith/smith-api/runs/get-the-langsmith-ui-url-for-a-run
  - https://docs.langchain.com/langsmith/smith-api/runs/list-runs-in-a-trace
  - https://docs.langchain.com/langsmith/smith-api/runs/query-public-shared-trace-runs
  - https://docs.langchain.com/langsmith/smith-api/runs/query-runs
  - https://docs.langchain.com/langsmith/smith-api/runs/query-traces
  - https://docs.langchain.com/langsmith/smith-api/runs/share-a-run
  - https://docs.langchain.com/langsmith/smith-api/runs/unshare-a-run
last_verified: 2026-08-11
---

# 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 做有界退避。