细粒度计费使用量

追踪使用量： 对于 LangSmith Cloud，细粒度可计费追踪数据的收集于 2026 年 1 月 5 日开始。对于在此日期之前摄入的追踪数据，不提供相关数据。对于 Self-hosted 实例，追踪数据收集会在通过以下环境变量启用该功能时开始，或者在升级到默认启用该功能的版本后开始。

DEFAULT_ORG_FEATURE_ENABLE_GRANULAR_USAGE_REPORTING=true
GRANULAR_USAGE_TABLE_ENABLED=true

从 Self-hosted 0.16.0 版本开始，Self-hosted 部署不再跟踪长期保留追踪的使用量。对于这些部署，仅长期保留保留期限筛选器始终显示零结果。LangSmith Deployment 使用量使用单独的数据源。有关更多详细信息，请参阅 LangSmith Deployment 部分。

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

追踪使用量（kind=traces，默认）：摄入的追踪数量。
LangSmith Deployment 使用量（kind=langsmith_deployments）：对于 LangSmith Deployment，执行的节点数、代理运行次数和代理运行时长。

两种类型共享相同的查询参数（时间范围、工作区筛选器、分组维度），并返回相同的按时间分桶的数据结构。两者的数据源相互独立，因此某种类型返回的记录不会出现在另一种类型中。这些 API 支持你：

跟踪不同团队或工作区的使用量。
确定哪些用户或 API 密钥消耗的追踪数量最多，或运行的代理数量最多。
分析一段时间内的使用模式。
导出使用量数据，用于内部报告。

前置条件

你必须拥有 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 标签页显示三个统计卡片（执行的节点总数 / 代理运行总数 / 代理运行总时长（秒）），并为每个指标垂直堆叠显示一个图表，因为这三个指标使用不同的单位。

查询参数

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

参数	类型	必填	描述
`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`）

响应

{
  "stride": {
    "days": 1,
    "hours": 0
  },
  "usage": [
    {
      "time_bucket": "2026-01-15T00:00:00Z",
      "dimensions": {
        "workspace_id": "uuid",
        "workspace_name": "我的工作区"
      },
      "traces": 1500
    }
  ]
}

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

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']} 条追踪")

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} 条追踪`);
}

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>"

示例：按用户获取追踪使用量，仅筛选长期保留数据

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", "未知")
    print(f"{user_email}: {record['traces']} 条长期保留追踪")

LangSmith Deployment 使用量（`kind=langsmith_deployments`）

每条记录会同时包含三个指标，因此单次获取即可支持完整的 Deployment 视图。

LangSmith Deployment 使用量来自与追踪使用量不同的数据源，并且在 Deployment 使用量的完整保留窗口内可用。对于 Self-hosted 实例，Deployment 使用量端点采用选择加入方式。通过以下配置启用：

REMOTE_METRICS_ROLLUP_ENABLED=true

或者升级到默认启用该功能的 LangSmith 版本（请参阅 Self-hosted 更新日志）。

响应

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

字段	描述
`nodes_executed`	时间桶内执行的 LangGraph 节点总数。
`agent_runs`	时间桶内的代理运行总次数（图调用次数）。
`agent_uptime_seconds`	副本运行总时长，单位为秒，按部署副本求和。用于计费的去重后待机分钟数由计费管道单独计算；此字段是用于明细和分析的原始总和。

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

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']} 个节点，"
        f"{record['agent_runs']} 次运行，"
        f"{record['agent_uptime_seconds']} 秒运行时长"
    )

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} 个节点，` +
    `${record.agent_runs} 次运行，${record.agent_uptime_seconds} 秒运行时长`
  );
}

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 将其作为电子表格公式进行计算。

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)

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`	两种类型
`project`	按项目分组	`project_id`、`project_name`	两种类型
`user`	按用户分组	`user_id`、`user_email`	两种类型
`api_key`	按 API 密钥分组	`api_key_short_key`	两种类型

对于追踪使用量，“项目”指 LangSmith tracer session。对于 Deployment 使用量，“项目”指 LangSmith Deployment 项目（已部署的代理）。

Billing & usage

前置条件

在 UI 中查看

查询参数

按天粒度的约定

步长

兼容性

API 端点

追踪使用量（`kind=traces`）

响应

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

示例：按用户获取追踪使用量，仅筛选长期保留数据

LangSmith Deployment 使用量（`kind=langsmith_deployments`）

响应

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

CSV 导出

分组选项

相关资源

​前置条件

​在 UI 中查看

​查询参数

​按天粒度的约定

​步长

​兼容性

​API 端点

​追踪使用量（kind=traces）

​响应

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

​示例：按用户获取追踪使用量，仅筛选长期保留数据

​LangSmith Deployment 使用量（kind=langsmith_deployments）

​响应

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

​CSV 导出

​分组选项

​相关资源

前置条件

在 UI 中查看

查询参数

按天粒度的约定

步长

兼容性

API 端点

追踪使用量（`kind=traces`）

响应

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

示例：按用户获取追踪使用量，仅筛选长期保留数据

LangSmith Deployment 使用量（`kind=langsmith_deployments`）

响应

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

CSV 导出

分组选项

相关资源