细粒度计费使用量

对于 LangSmith Cloud，细粒度计费使用数据的收集始于 2026 年 1 月 5 日。此日期之前的使用数据不可用。对于自托管实例，数据收集在通过以下环境变量启用该功能后开始，或在升级到默认启用该功能的版本之后开始。

DEFAULT_ORG_FEATURE_ENABLE_GRANULAR_USAGE_REPORTING=true
GRANULAR_USAGE_TABLE_ENABLED=true

LangSmith 提供细粒度计费使用 API，允许您获取按工作区、项目、用户或 API 密钥细分的详细跟踪使用数据。这使您能够：

跟踪不同团队或工作区的使用情况
识别哪些用户或 API 密钥消耗了最多的跟踪
分析随时间变化的使用模式
导出使用数据用于内部报告

先决条件

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

在 UI 中查看

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

导航到 Settings > Billing and Usage
选择 Granular Usage 选项卡
使用控件：
- 选择时间范围：
  - 最近 7 天、30 天、3 个月、6 个月、1 年或自定义
- 选择聚合级别（每日、每周或每月）
- 按工作区、项目、用户或 API 密钥分组
- 筛选特定工作区
点击 Export CSV 下载数据

API 端点

获取细粒度使用数据

使用灵活的分组选项检索细粒度使用数据。

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

查询参数

参数	类型	必需	描述
`start_time`	datetime	是	时间范围的开始（ISO 8601 格式）
`end_time`	datetime	是	时间范围的结束（必须在 start_time 之后）
`workspace_ids`	UUID 数组	是	将结果筛选到特定工作区
`group_by`	string	否	分组维度。可选值：`workspace`、`project`、`user`、`api_key`。默认值：`workspace`

响应

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

stride 字段表示用于聚合的时间桶大小，根据请求的时间范围计算：

时间范围	聚合方式	Stride
小于 1 天	每小时	`hours: 1`
1-31 天	每日	`days: 1`
32-93 天（约 3 个月）	每周	`days: 7`
94-366 天（约 1 年）	每月	`days: 30`
超过 366 天	每年	`days: 365`

示例：按工作区获取使用情况

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

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

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

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

将使用情况导出为 CSV

将细粒度使用数据导出为可下载的 CSV 文件。

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

此端点接受与细粒度使用端点相同的查询参数，并返回一个 CSV 文件。 CSV 始终包含所有列，但只有与所选 group_by 选项相关的列会被填充：

列	描述
Time Bucket Start	时间桶的开始
Time Bucket End	时间桶的结束
Workspace ID	工作区的 UUID（当按工作区分组时）
Workspace Name	工作区的名称（当按工作区分组时）
Project ID	项目的 UUID（当按项目分组时）
Project Name	项目的名称（当按项目分组时）
User ID	用户的 UUID（当按用户分组时）
User Email	用户的电子邮件（当按用户分组时）
API Key Short Key	API 密钥的短标识符（当按 API 密钥分组时）
Traces	时间桶内的跟踪数量

示例：导出为 CSV

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

# 保存到文件
with open("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?\
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 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`

Account administration

Tools

Additional resources

先决条件

在 UI 中查看

API 端点

获取细粒度使用数据

查询参数

响应

示例：按工作区获取使用情况

示例：按用户获取使用情况

将使用情况导出为 CSV

示例：导出为 CSV

分组选项

相关资源

​先决条件

​在 UI 中查看

​API 端点

​获取细粒度使用数据

​查询参数

​响应

​示例：按工作区获取使用情况

​示例：按用户获取使用情况

​将使用情况导出为 CSV

​示例：导出为 CSV

​分组选项

​相关资源

先决条件

在 UI 中查看

API 端点

获取细粒度使用数据

查询参数

响应

示例：按工作区获取使用情况

示例：按用户获取使用情况

将使用情况导出为 CSV

示例：导出为 CSV

分组选项

相关资源