细粒度可计费用量

检索按工作区、项目、用户或 API 密钥细分的详细追踪和 LangSmith Deployment 用量数据。

NOTE

追踪用量： 对于 LangSmith Cloud，可计费细粒度追踪数据收集始于 2026 年 1 月 5 日。在此日期之前摄取的追踪没有可用数据。

对于自托管实例，追踪数据收集会在通过以下环境变量启用该功能时开始，或在升级到一个默认启用它的版本之后开始。

env

DEFAULT_ORG_FEATURE_ENABLE_GRANULAR_USAGE_REPORTING=true
GRANULAR_USAGE_TABLE_ENABLED=true

从自托管 0.16.0 版开始，自托管部署不再跟踪长生命周期追踪用量。对这些部署而言，Long-lived only 保留筛选器始终显示零结果。

LangSmith Deployment 用量使用一个独立的数据源。更多详情，参阅 LangSmith Deployment 部分。

LangSmith 提供细粒度可计费用量 API，让你能够检索按工作区、项目、用户或 API 密钥细分的详细用量数据。同一个端点支持两个可计费域，通过一个 kind 查询参数选择：

追踪用量（kind=traces，默认）：摄取的追踪数量。
LangSmith Deployment 用量（kind=langsmith_deployments）：LangSmith Deployment 所执行的节点、agent 运行和 agent 运行时长。

两种 kind 共享相同的查询参数（时间范围、工作区过滤器、分组维度），并返回相同的按时间分桶的形状。数据源是分开的，因此一种 kind 返回的记录不会出现在另一种中。

这些 API 让你能够：

跨不同团队或工作区跟踪用量。
识别哪些用户或 API 密钥消耗了最多的追踪或运行了最多的 agent。
随时间分析用量模式。
为内部报告导出用量数据。

前置条件

你必须拥有 organization:read 权限才能访问细粒度用量数据。
你只能查看你有读取权限的工作区的用量。

在 UI 中查看

你也可以在 LangSmith UI 中查看细粒度用量数据：

导航到 Settings > Billing and Usage
选择 Granular Usage 标签
在 LangSmith Traces 和 LangSmith Deployments 子标签之间切换以查看各个域。活动的子标签会反映在 URL 中（?tab=traces 或 ?tab=deployments），因此你可以将页面加书签以落到同一个视图。
使用这些控件来：
- 选择一个时间范围（最近 7 天、30 天、3 个月、6 个月、1 年或自定义）
- 按工作区、项目、用户或 API 密钥分组
- 过滤到特定工作区
- 在 LangSmith Traces 标签上，可选地按保留层级过滤（All Retention / Long-lived only / Short-lived only）
点击 Export CSV 以下载活动标签的数据。

时间范围和工作区过滤器在两个子标签之间共享，切换标签会保留你所选的内容。LangSmith Deployments 标签显示三张统计卡（Total Nodes Executed / Total Agent Runs / Total Agent Uptime (seconds)）以及每个指标一张纵向堆叠的图，因为这些指标使用不同的单位。

查询参数

细粒度用量端点接受以下查询参数：

参数	类型	必需	描述
`start_time`	datetime	是	时间范围的开始（ISO 8601 格式）。
`end_time`	datetime	是	时间范围的结束。必须晚于 `start_time`。
`workspace_ids`	array of UUIDs	是	将结果过滤到特定工作区。
`kind`	string	否	`traces`（默认）或 `langsmith_deployments`。选择可计费域。
`group_by`	string	否	要分组的维度。以下之一：`workspace`、`project`、`user`、`api_key`。默认：`workspace`。
`trace_tier`	string	否	仅追踪的保留过滤器：`longlived` 或 `shortlived`。省略表示全部保留。当 `kind=langsmith_deployments` 时忽略。

按天粒度的约定

用量数据按天粒度聚合。该端点在 API 层将窗口规范化为整天：

start_time 向下取整到其所在日的 UTC 午夜。
end_time 向上取整到下一个 UTC 午夜（已是午夜时为无操作）。
与所请求窗口重叠的任何一天都会被完整地包含进来。

因此，从 2026-01-01T12:00:00Z 到 2026-01-02T12:00:00Z 的 24 小时窗口会返回完整的 1 月 1 日和 1 月 2 日两个桶的用量。

步长

每个响应中的 stride 字段指示用于聚合的时间桶大小，它根据所请求的时间范围计算得出。每日是最小值。亚日窗口仍按一天分桶。

时间范围	聚合	步长
最多 31 天	每日	`days: 1`
32–93 天（~3 个月）	每周	`days: 7`
94–366 天（~1 年）	每月	`days: 30`
超过 366 天	每年	`days: 365`

兼容性

将 kind=langsmith_deployments 与 group_by=trace_tier 组合会返回 400 Bad Request。保留层级仅适用于追踪。

API 端点

GET /api/v1/orgs/current/billing/granular-usage

省略 kind 的现有调用方会继续以它们一直以来相同的响应形状获得追踪用量。

追踪用量（`kind=traces`）

响应

json

{
  "stride": {
    "days": 1,
    "hours": 0
  },
  "usage": [
    {
      "time_bucket": "2026-01-15T00:00:00Z",
      "dimensions": {
        "workspace_id": "uuid",
        "workspace_name": "My Workspace"
      },
      "traces": 1500
    }
  ]
}

示例：按工作区获取追踪用量

PythonTypeScriptcURL

python

import httpx
from datetime import datetime, timedelta, timezone

client = httpx.Client(
    base_url="https://api.smith.langchain.com",
    headers={"x-api-key": "<your-api-key>"}
)

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(days=30)

response = client.get(
    "/api/v1/orgs/current/billing/granular-usage",
    params={
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "workspace_ids": ["<workspace-id>"],
        "group_by": "workspace",
    },
)

data = response.json()
for record in data["usage"]:
    print(f"{record['time_bucket']}: {record['traces']} traces")

typescript

const response = await fetch(
  `https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?` +
  new URLSearchParams({
    start_time: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
    end_time: new Date().toISOString(),
    workspace_ids: "<workspace-id>",
    group_by: "workspace",
  }),
  {
    headers: {
      "x-api-key": "<your-api-key>",
    },
  }
);

const data = await response.json();
for (const record of data.usage) {
  console.log(`${record.time_bucket}: ${record.traces} traces`);
}

bash

curl -X GET "https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?\
start_time=2026-01-01T00:00:00Z&\
end_time=2026-01-15T00:00:00Z&\
workspace_ids=<workspace-id>&\
group_by=workspace" \
  -H "x-api-key: <your-api-key>"

示例：按用户获取追踪用量，并过滤为仅长生命周期保留

Python

python

response = client.get(
    "/api/v1/orgs/current/billing/granular-usage",
    params={
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "workspace_ids": ["<workspace-id>"],
        "group_by": "user",
        "trace_tier": "longlived",
    },
)

data = response.json()
for record in data["usage"]:
    user_email = record["dimensions"].get("user_email", "Unknown")
    print(f"{user_email}: {record['traces']} long-lived traces")

LangSmith Deployment 用量（`kind=langsmith_deployments`）

每条记录都一并带有三个指标，因此单次获取就能支撑整个 Deployment 视图。

NOTE

LangSmith Deployment 用量的数据源与追踪用量分开，并在你的部署用量的完整保留窗口内可用。

对于自托管实例，Deployment 用量端点需要选择启用。通过以下方式启用它：

env

REMOTE_METRICS_ROLLUP_ENABLED=true

或升级到一个默认启用它的 LangSmith 版本（参阅自托管变更日志）。

响应

json

{
  "stride": {
    "days": 1,
    "hours": 0
  },
  "usage": [
    {
      "time_bucket": "2026-01-15T00:00:00Z",
      "dimensions": {
        "workspace_id": "uuid",
        "workspace_name": "My Workspace"
      },
      "nodes_executed": 12500,
      "agent_runs": 320,
      "agent_uptime_seconds": 86400
    }
  ]
}

字段	描述
`nodes_executed`	该时间桶内执行的 LangGraph 节点总数。
`agent_runs`	该时间桶内的 agent 运行总数（图调用）。
`agent_uptime_seconds`	跨部署副本求和的副本总运行时长，以秒计。用于开票的去重后备分钟由计费管道单独计算；此字段是为细分和分析而呈现的原始求和。

示例：按工作区获取 Deployment 用量

PythonTypeScriptcURL

python

response = client.get(
    "/api/v1/orgs/current/billing/granular-usage",
    params={
        "kind": "langsmith_deployments",
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "workspace_ids": ["<workspace-id>"],
        "group_by": "workspace",
    },
)

data = response.json()
for record in data["usage"]:
    print(
        f"{record['time_bucket']}: "
        f"{record['nodes_executed']} nodes, "
        f"{record['agent_runs']} runs, "
        f"{record['agent_uptime_seconds']}s uptime"
    )

typescript

const response = await fetch(
  `https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?` +
  new URLSearchParams({
    kind: "langsmith_deployments",
    start_time: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
    end_time: new Date().toISOString(),
    workspace_ids: "<workspace-id>",
    group_by: "workspace",
  }),
  {
    headers: {
      "x-api-key": "<your-api-key>",
    },
  }
);

const data = await response.json();
for (const record of data.usage) {
  console.log(
    `${record.time_bucket}: ${record.nodes_executed} nodes, ` +
    `${record.agent_runs} runs, ${record.agent_uptime_seconds}s uptime`
  );
}

bash

curl -X GET "https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?\
kind=langsmith_deployments&\
start_time=2026-01-01T00:00:00Z&\
end_time=2026-01-15T00:00:00Z&\
workspace_ids=<workspace-id>&\
group_by=workspace" \
  -H "x-api-key: <your-api-key>"

CSV 导出

GET /api/v1/orgs/current/billing/granular-usage/export

与数据端点相同的查询参数，包括 kind。返回一个 CSV 文件，每个（时间桶，维度）元组一行。所有维度列始终存在；只有与所选 group_by 匹配的列会被填充。

对于 kind=traces，值列是 Traces。对于 kind=langsmith_deployments，值列是 Nodes Executed、Agent Runs 和 Agent Uptime (seconds)。

列	何时存在
Time Bucket Start	始终
Time Bucket End	始终
Workspace ID / Name	始终（当 `group_by=workspace` 时填充）
Project ID / Name	始终（当 `group_by=project` 时填充）
User ID / Email	始终（当 `group_by=user` 时填充）
API Key Short Key	始终（当 `group_by=api_key` 时填充）
Traces	`kind=traces`
Nodes Executed / Agent Runs / Agent Uptime (seconds)	`kind=langsmith_deployments`

对于值将以 =、+、-、@、制表符或回车开头的单元格，会加上制表符前缀，以中和 Excel / Google Sheets / LibreOffice 中的电子表格公式求值。

PythoncURL

python

response = client.get(
    "/api/v1/orgs/current/billing/granular-usage/export",
    params={
        "kind": "langsmith_deployments",
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "workspace_ids": ["<workspace-id>"],
        "group_by": "workspace",
    },
)

with open("deployment_usage_report.csv", "wb") as f:
    f.write(response.content)

bash

curl -X GET "https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage/export?\
kind=langsmith_deployments&\
start_time=2026-01-01T00:00:00Z&\
end_time=2026-01-15T00:00:00Z&\
workspace_ids=<workspace-id>&\
group_by=workspace" \
  -H "x-api-key: <your-api-key>" \
  -o deployment_usage_report.csv

分组选项

group_by 参数决定用量数据如何被聚合：

值	描述	返回的维度	适用于
`workspace`	按工作区分组	`workspace_id`、`workspace_name`	两种 kind
`project`	按项目分组	`project_id`、`project_name`	两种 kind
`user`	按用户分组	`user_id`、`user_email`	两种 kind
`api_key`	按 API 密钥分组	`api_key_short_key`	两种 kind

对于追踪用量，“project”指的是 LangSmith 追踪会话。对于 Deployment 用量，“project”指的是 LangSmith Deployment 项目（一个已部署的 agent）。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织