---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - tracing
  - analytics
topic: LangSmith Smith API Run v1 查询、统计、线程预览与删除
sources:
  - https://docs.langchain.com/langsmith/smith-api/run/delete-runs
  - https://docs.langchain.com/langsmith/smith-api/run/delete-runs-abac
  - https://docs.langchain.com/langsmith/smith-api/run/generate-query-for-runs
  - https://docs.langchain.com/langsmith/smith-api/run/group-runs
  - https://docs.langchain.com/langsmith/smith-api/run/query-runs
  - https://docs.langchain.com/langsmith/smith-api/run/read-run
  - https://docs.langchain.com/langsmith/smith-api/run/read-run-share-state
  - https://docs.langchain.com/langsmith/smith-api/run/share-run
  - https://docs.langchain.com/langsmith/smith-api/run/stats-group-runs
  - https://docs.langchain.com/langsmith/smith-api/run/stats-runs
  - https://docs.langchain.com/langsmith/smith-api/run/thread-preview
  - https://docs.langchain.com/langsmith/smith-api/run/unshare-run
  - https://docs.langchain.com/langsmith/smith-api/run/validate-runs-query
last_verified: 2026-08-11
---

# Run v1：查询、统计、线程预览与删除

v1 `run` 组提供了查询、聚合、统计、自然语言生成 filter、Thread 预览、旧共享契约与破坏性删除。它与 v2 Run API 并存，不能只根据路径名相似就混用请求/响应 schema。

## 能力表

| 能力 | 方法与路径 | 要点 |
|---|---|---|
| 查询 | `POST /api/v1/runs/query` | `BodyParamsForRunsQuerySchema` → runs + cursors |
| 语法验证 | `POST /api/v1/runs/query/validate` | `valid` + errors；OpenAPI 未声明认证 |
| 自然语言转 filter | `POST /api/v1/runs/generate-query` | `query` → filter + feedback URLs |
| 读单 Run | `GET /api/v1/runs/{run_id}` | 可带 session/start time 及排除大字段开关 |
| 分组 / 分组统计 | `POST /api/v1/runs/group` / `group/stats` | session + group_by |
| 全局统计 | `POST /api/v1/runs/stats` | 必填 session 数组 |
| Thread 预览 | `GET /api/v1/runs/threads/{thread_id}` | 必填 `session_id`，可选 select/variables |
| 共享状态 / 共享 / 取消 | `GET` / `PUT` / `DELETE /api/v1/runs/{run_id}/share` | v1 共享契约 |
| 删除条件集 | `POST /api/v1/runs/delete` | trace IDs 或 metadata，可波及 examples |
| ABAC Trace 删除 | `POST /api/v1/runs/delete/traces` | 必填 session + trace IDs |

## 查询模型与翻页

`/runs/query` 支持 ID、trace/parent、run type、sessions、reference examples、时间、error、root、filter/trace_filter/tree_filter、实验搜索和字段 `select`。默认 `limit=100`，响应是 `runs`、分页 `cursors`、可选 search cursors 与 parsed query。

特别边界：传 `trace` 时 `limit` 和 cursor pagination 不生效，会在单次响应返回整个 Trace 的 Runs。大 Trace 上调用前应评估响应体和网关上限，必要时改用 v2 投影和时间窗。

`validate-runs-query` 只验证语法，不代替 tenant/session 授权。当前 OpenAPI 对此 operation 没有 security requirement，如自托管暴露公网，应由 ingress 限流、限 body 并避免错误信息泄露解析器细节。

## 自然语言生成的 filter 不可直接执行

`generate-query` 输入自然语言 `query`，返回 filter 和多个用于产品反馈的 URL（如用户选择/打开 Run、结果大小、filter 是否有效）。生成 filter 应视为不可信输出：先 validate，展示给用户审查，再由服务端强制 workspace/session 与最大时间窗；反馈 URL 同样按 capability URL 保护，不记日志或转发给第三方分析。

## 聚合与成本指标

`RunGroupRequest` 必填 `session_id` 和 `group_by`，可按 name/run_type/tag/metadata 及 metadata path 分组，并有时间、filter、offset/limit。`stats` 可返回 count、latency/first-token P50/P99、token 和 cost 总量/分位、error/streaming rate、feedback stats 及细分。

监控报表必须固定时区、时间窗、filter 和分组定义，同时记录无数据、部分数据与延迟到达；`null` 指标不能当 0。费用是根据模型价格映射估算，应保存价格版本与数据窗口，不作为财务对账的唯一来源。

## 共享与读取最小化

读单 Run 可用 `exclude_s3_stored_attributes`、`exclude_serialized`、`include_messages` 控制负载。默认不要拉取 serialized/messages 到列表或日志。v1 share 先读状态，再显式 PUT；撤销后不应假定旧链接在所有下游缓存立即消失。

## 删除是高风险作业

`/runs/delete` 可传 `session_id`、`trace_ids`、metadata、`start_time`，还有 `delete_examples` 开关；ABAC 版强制 `session_id + trace_ids`。执行前应：

1. 用同一作用域先 query/count 生成待删 Trace ID 快照；
2. 双人审批 tenant/session、数量、时间范围和 `delete_examples`；
3. 分批、限速、以 trace ID 精确删除，记录不含载荷的审计清单；
4. 删后重查 Run、Feedback、数据集关联和公开 share state。

文档没有承诺级联、恢复或幂等语义，不应仅因 HTTP 200 就宣称数据已完全清理。