---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - charts
  - monitoring
topic: LangSmith Smith API Charts 可观测仪表盘与已退役 Organization 接口
sources:
  - https://docs.langchain.com/langsmith/smith-api/charts/clone-section
  - https://docs.langchain.com/langsmith/smith-api/charts/create-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/create-section
  - https://docs.langchain.com/langsmith/smith-api/charts/delete-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/delete-section
  - https://docs.langchain.com/langsmith/smith-api/charts/org-create-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/org-create-section
  - https://docs.langchain.com/langsmith/smith-api/charts/org-delete-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/org-delete-section
  - https://docs.langchain.com/langsmith/smith-api/charts/org-read-chart-preview
  - https://docs.langchain.com/langsmith/smith-api/charts/org-read-charts
  - https://docs.langchain.com/langsmith/smith-api/charts/org-read-sections
  - https://docs.langchain.com/langsmith/smith-api/charts/org-read-single-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/org-read-single-section
  - https://docs.langchain.com/langsmith/smith-api/charts/org-update-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/org-update-section
  - https://docs.langchain.com/langsmith/smith-api/charts/read-chart-preview
  - https://docs.langchain.com/langsmith/smith-api/charts/read-charts
  - https://docs.langchain.com/langsmith/smith-api/charts/read-sections
  - https://docs.langchain.com/langsmith/smith-api/charts/read-single-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/read-single-section
  - https://docs.langchain.com/langsmith/smith-api/charts/update-chart
  - https://docs.langchain.com/langsmith/smith-api/charts/update-section
last_verified: 2026-08-11
---

# Charts 可观测仪表盘与已退役 Org 接口

Charts API 把 workspace 内的 tracing 指标定义为 Section → Chart/Text Block → Series 的层级。配置和数据读取是两件事：同一 Chart 只有结合时间窗、时区、stride 和 filter 后才产生可比较的数据。

## Workspace Charts 生命周期

| 资源 | 创建 | 读取 | 更新 | 删除 |
|---|---|---|---|---|
| Section | `POST /api/v1/charts/section` | `GET .../section`；`POST .../section/{id}` | `PATCH .../section/{id}` | `DELETE .../section/{id}` |
| Chart/Text | `POST /api/v1/charts/create` | `POST /api/v1/charts`；`POST .../{chart_id}` | `PATCH .../{chart_id}` | `DELETE .../{chart_id}` |

额外操作：

- `POST /api/v1/charts/preview`：不保存就运行 chart 预览；
- `POST /api/v1/charts/section/clone`：用 `section_id` 和可选 `session_id` 复制 dashboard；
- `GET /api/v1/charts/section`：`limit=100, offset=0`，可按 title、IDs、sort、tag 筛选。

“读 Charts”使用 POST，因为时间窗和查询配置在 body；它在业务语义上是只读，但 CDN/浏览器不会像 GET 一样默认缓存。如要应用级缓存，key 必须包含 workspace/permission、规范化 body、Chart 版本和时间桶。

## Section、Chart 与 Text Block

Section 创建必填 title，可带 description/index；更新还可改 dashboard layout。Chart 创建必填 title、`chart_type`、series，type 枚为 `line|bar|table|kpi|top-k|pie`。Text Block 使用同一创建端点，必填 chart_type、section_id 和 markdown。

Series 包含 name、metric/project metric/feedback key/workspace、新式 metric definition、group-by definitions 和 filter definition。通用 filters 中可有 `filter`、`trace_filter`、`tree_filter`、session IDs；group-by 支持 name/run_type/tag/metadata path 并用 `max_groups` 限制基数。

Chart/Text 同时是 union schema，客户端应先按 `chart_type` 或返回形状做鉴别再解析。Markdown 按不可信输入消毒，禁止 script、事件属性、危险 URL scheme 和任意 iframe。

PATCH schema 用 `Missing` 区分“未传”与 `null`：未改字段要省略，只在契约明确允许清空时传 null。不要将本地默认值序列化成全量 PATCH，否则会覆盖并发编辑。

## 时间桶、预览和载荷控制

Charts 读取的公共请求字段：

- `timezone` 默认 UTC；
- `start_time/end_time`；
- `stride={days,hours,minutes}`；
- `omit_data`默认 false；
- 列表还可用 `after_index` 与 tag，Section 读取可 group-by。

Preview 必填 `bucket_info` 和待测 chart。编辑器应采用 debounce/cancel stale request，为预览限最大窗口、系列数和 group cardinality；先 `omit_data=true` 取元数据/布局，可见区域再加载数据。趋势对比必须保持 timezone/stride/filter 一致，不将空桶等同 0。

## Organization Charts 全部已退役

以下 11 个 `/api/v1/org-charts...` 端点的描述都明确：**organization usage charts have been retired (HTTP 410)**：创建/读取/预览/更新/删除 Chart 与 Section 全部不再可用。

当前 OpenAPI 仍为这些 operation 列出空 200 响应，且多个含 `{chart_id}` 或 `{section_id}` 的退役路径不再声明对应 path parameter。这是已验证的文档/形式 schema 不一致，不代表运行时仍会 200。新客户端不生成/暴露这些能力；老客户端对 410 停止重试、禁用界面，并迁移到 workspace Charts 或当前用量报表。

## 删除、并发和可观测性

删 Section 前先枚举 chart count 与子 section/layout 依赖；文档未声明是拒绝、级联还是孤立 Chart，未实测前必须当高风险操作。OpenAPI 未提供 ETag/版本字段，多人编辑应在业务层对比 last-read 快照并提示冲突。

监控 Chart API 本身的 p50/p95、扫描窗口、系列/数据点数、超时、422、缓存命中和废弃 410 调用量；不在日志中完整输出 filter 、metadata 或图表数据。