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

• 追踪用量 (kind=traces（默认）：摄取的追踪数量。
• LangSmith Deployment 用量 (kind=langsmith_deployments）：执行的节点数、代理运行次数和代理运行时间（适用于 LangSmith Deployment.

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

这些 API 使您能够：

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

前提条件

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

在 UI 中查看

您也可以在 LangSmith UI:

1. 导航到 **设置** > **账单和使用情况** 2. 选择 **细粒度使用情况** 标签页 3. 在 **LangSmith Traces** 和 **LangSmith Deployments** 子标签页之间切换以查看各个域。活动子标签页会反映在 URL 中 (?tab=traces or ?tab=deployments)，因此您可以添加书签以返回同一视图。 4. 使用控制选项： - 选择时间范围（最近 7 天、30 天、3 个月、6 个月、1 年或自定义） - 按工作区、项目、用户或 API 密钥分组 - 筛选特定工作区 - 在 **LangSmith 追踪** 标签页，可按保留层级筛选 (All Retention / Long-lived only / Short-lived only) 5. 点击 **导出 CSV** 下载当前标签页的数据。

时间范围和工作区筛选器在两个子标签页之间共享，切换标签页会保留您的选择。 **LangSmith 部署** tab shows three stat cards (Total Nodes Executed / Total Agent Runs / Total Agent Uptime (seconds)) and one chart per metric stacked vertically, since the three metrics use different units.

查询参数

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

日粒度合同

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

• - start_time 向下取整至当天的 UTC 午夜。
• - end_time 向上取整至下一个 UTC 午夜（已是午夜时则不变）。
• - 与请求时间窗口重叠的任何日期都会被完整包含。

从某个时间点开始的24小时窗口 2026-01-01T12:00:00Z to 2026-01-02T12:00:00Z 因此返回1月1日和1月2日完整时段的使用量。

步幅

每个响应中的 stride 字段指示用于聚合的时间桶大小，根据请求的时间范围计算。最小为每日。少于一天的时间窗口仍按一天进行分桶。

兼容性

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": "My Workspace"
      },
      "traces": 1500
    }
  ]
}

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

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",
        "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部署使用量 (kind=langsmith_deployments)

每条记录同时携带三个指标，单次获取即可支持整个部署视图。

响应

{
  "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
    }
  ]
}

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

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

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

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

值以以下内容开头的单元格 =, +, -, @, tab, or carriage-return are tab-prefixed to neutralize spreadsheet formula evaluation in 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 决定使用量数据的聚合方式：

对于追踪使用量，“项目”指 LangSmith 追踪器会话。对于部署使用量，“项目”指 LangSmith 部署项目（已部署的代理）。

相关资源

• - 在您的账户中管理计费
• - 组织和工作区操作