Skip to main content
对于 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 中查看细粒度使用数据：
  1. 导航到 Settings > Billing and Usage
  2. 选择 Granular Usage 选项卡
  3. 使用控件：
    • 选择时间范围：
      • 最近 7 天、30 天、3 个月、6 个月、1 年或自定义
    • 选择聚合级别（每日、每周或每月）
    • 按工作区、项目、用户或 API 密钥分组
    • 筛选特定工作区
  4. 点击 Export CSV 下载数据

​
API 端点

​
获取细粒度使用数据

使用灵活的分组选项检索细粒度使用数据。 
GET /api/v1/orgs/current/billing/granular-usage

​
查询参数

参数类型必需描述
start_timedatetime是时间范围的开始（ISO 8601 格式）
end_timedatetime是时间范围的结束（必须在 start_time 之后）
workspace_idsUUID 数组是将结果筛选到特定工作区
group_bystring否分组维度。可选值：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")

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

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 KeyAPI 密钥的短标识符（当按 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)

​
分组选项

group_by 参数决定使用数据的聚合方式：
值描述返回的维度
workspace按工作区分组workspace_id、workspace_name
project按项目分组project_id、project_name
user按用户分组user_id、user_email
api_key按 API 密钥分组api_key_short_key

​
相关资源

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。