用量查询 API 与 SDK
查询当前配额与近一年历史周期的浏览器、WebFetch 和官方代理用量。
可用性
请确认目标环境已启用用量 API,并安装包含 client.usage 的 SDK 版本;旧版本不一定支持。
鉴权与请求规则
使用项目对应的 API Key 和 Project ID,在可信服务端调用。Base URL 是目标环境的 API origin,不带 /v1 或其他路径。以下使用 LEXMOUNT_BASE_URL 显式指定环境,避免误调用。
| 请求头 | 必填 | 说明 |
|---|---|---|
API-Key | 是 | 项目的有效密钥 |
Project-Id | 是 | 必须与密钥绑定项目一致 |
两个接口都只接受 GET,不接受任何查询参数,不需要请求体。不能通过参数覆盖项目、时间范围或分页;不要重复发送鉴权请求头。无需创建浏览器 session。密钥不要放在 URL、前端代码或日志中。
export LEXMOUNT_BASE_URL='https://api.lexmount.cn' # 换成实际已部署的目标环境
export LEXMOUNT_API_KEY='YOUR_API_KEY'
export LEXMOUNT_PROJECT_ID='YOUR_PROJECT_ID'
curl --silent --show-error \
-H "API-Key: $LEXMOUNT_API_KEY" \
-H "Project-Id: $LEXMOUNT_PROJECT_ID" \
"$LEXMOUNT_BASE_URL/v1/usage/current"
curl --silent --show-error \
-H "API-Key: $LEXMOUNT_API_KEY" \
-H "Project-Id: $LEXMOUNT_PROJECT_ID" \
"$LEXMOUNT_BASE_URL/v1/usage/history"GET /v1/usage/current
返回当前配额周期的已用量、基础配额和剩余额度。成功 HTTP 200,响应结构为 { "request_id": "...", "data": {...} }。
| data 字段 | 类型 | 含义 |
|---|---|---|
project_id | string | 查询的项目 |
as_of | string | 查询时刻,RFC 3339 时间戳 |
timezone | string | 固定 Asia/Shanghai,配额周期计算时区 |
plan | string | 当前生效套餐标识 |
period_start / period_end | string | 周期开始/结束时间戳,起点包含、终点不包含 |
usage | object | 已用量,见下表 |
limits | object | 基础配额:browser_ms、webfetch_count、official_proxy_bytes |
remaining | object | 剩余额度,同 limits 字段,包含适用的赠送或购买额度 |
remaining 不一定等于 limits - usage,也可能超过基础配额。应直接使用服务端返回值,不自行从历史计数推导钱包余额。
usage 计数
| 字段 | 单位 | 含义 |
|---|---|---|
browser_ms | 毫秒 | 浏览器用量;除以 1000 换算秒 |
webfetch_count | 次 | WebFetch 用量 |
official_proxy_upload_bytes | 字节 | 官方代理上传流量 |
official_proxy_download_bytes | 字节 | 官方代理下载流量 |
official_proxy_total_bytes | 字节 | 官方代理上传与下载合计 |
API 不包含 WebSearch、验证码用量,也不把本地/外部代理流量当作官方代理流量。
以下是结构示例,不是真实账户返回值;数值不代表任何套餐承诺:
{
"request_id": "example-request-id",
"data": {
"project_id": "example-project-id",
"as_of": "2026-11-05T08:00:00.000Z",
"timezone": "Asia/Shanghai",
"plan": "pro",
"period_start": "2026-10-31T16:00:00.000Z",
"period_end": "2026-11-30T16:00:00.000Z",
"usage": {
"browser_ms": 1000,
"webfetch_count": 3,
"official_proxy_upload_bytes": 2,
"official_proxy_download_bytes": 3,
"official_proxy_total_bytes": 5
},
"limits": {"browser_ms": 10000, "webfetch_count": 100, "official_proxy_bytes": 1000},
"remaining": {"browser_ms": 9000, "webfetch_count": 97, "official_proxy_bytes": 995}
}
}GET /v1/usage/history
返回与过去 365 天相交的配额周期,按时间倒序排列,包含当前周期。不是固定自然月分桶,也不保证恰好 12 条;项目创建时间、套餐切换和配额锚点会影响周期数量。最早相交周期的起点可能早于 window_start。
成功 HTTP 200,同样包在 request_id 和 data 中。
| data 字段 | 类型 | 含义 |
|---|---|---|
project_id / as_of / timezone | string | 与 current 对应字段含义相同 |
window_start | string | 查询时刻往前 365 天 |
retained_since | string | 账本保留范围起点 |
accounting_basis | string | 固定 retained_reset_adjusted |
periods | array | 周期列表,最新在前 |
每个 period:
| 字段 | 类型 | 含义 |
|---|---|---|
period_start / period_end | string | 配额周期边界 |
plan | string | 该段生效套餐标识 |
coverage | string | retained 或 outside_retention |
usage | object 或 null | 与 current 相同的五个计数;保留范围外为 null |
Free 及专用 WebFetch 套餐使用共享身份配额;数字可能聚合该身份当前关联的多个项目,不只当前项目。响应不会泄露其他成员项目 ID。付费项目配额仅统计所查询的项目。
若周期起点早于保留起点,即便只有一部分超出保留范围,也返回 coverage: "outside_retention" 和 usage: null,不能当作 0。完整保留但没有用量的周期返回各项 0。
历史数据来自仍保留且按重置规则调整后的配额账本。管理重置、删除、延迟上报及共享身份成员变化可能影响统计;它不是不可变账单,也不返回历史钱包余额。当前周期尚未结束,计数可能继续增长。
历史响应中的单个不可用周期示例:
{
"period_start": "2025-10-31T16:00:00.000Z",
"period_end": "2025-11-30T16:00:00.000Z",
"plan": "free",
"coverage": "outside_retention",
"usage": null
}错误与限流
| HTTP 状态 | 常见含义 |
|---|---|
| 400 | 非法参数或重复安全请求头 |
| 401 | 缺少或无效密钥 |
| 403 | 项目与密钥不匹配,或账户/项目状态不允许访问 |
| 404 | 接口路径不存在 |
| 405 | 不支持的方法;应使用 GET |
| 429 | 请求限流 |
| 503 | 用量服务暂不可用 |
Gateway 错误格式示例:
{
"request_id": "example-request-id",
"error": {
"code": "invalid_request",
"message": "Usage queries do not accept query parameters.",
"details": {}
}
}Kong 提前拒绝的请求(例如鉴权、限流)可能使用不同错误结构,应先检查 HTTP 状态,不要假设所有错误都有上述字段。Gateway 响应包含 Cache-Control: no-store 和 X-Request-Id。
默认限流为每 consumer、每 Kong 节点每秒 2 次、每分钟 30 次,部署可以调整;不应把它理解为跨节点全局配额。收到 429 时降低轮询频率,并遵循响应中的 Retry-After(若有)。
Node.js SDK
需要包含 usage 的 SDK 版本。示例显式指定 API origin,使用构造器参数,不进行 session 地域发现。
import { Lexmount } from 'lexmount';
const client = new Lexmount({
apiKey: process.env.LEXMOUNT_API_KEY!,
projectId: process.env.LEXMOUNT_PROJECT_ID!,
baseURL: process.env.LEXMOUNT_BASE_URL!,
});
const current = await client.usage.current();
console.log(current.usage.browser_ms, current.remaining.webfetch_count);
const history = await client.usage.history();
for (const period of history.periods) {
if (period.usage === null) {
console.log(period.period_start, '历史数据不完整');
continue;
}
console.log(period.period_start, period.usage);
}
const response = await client.usage.current({
withResponse: true,
requestTimeoutMs: 30000,
maxRetries: 2,
});
console.log(response.request_id, response.status_code, response.data);默认直接返回 API 的 data。withResponse: true 返回包含 data/request_id/status_code/headers 的对象。超时单位是毫秒。
Python SDK
import os
from lexmount import Lexmount
with Lexmount(
api_key=os.environ['LEXMOUNT_API_KEY'],
project_id=os.environ['LEXMOUNT_PROJECT_ID'],
base_url=os.environ['LEXMOUNT_BASE_URL'],
) as client:
current = client.usage.current()
print(current.usage.browser_ms, current.remaining.webfetch_count)
history = client.usage.history()
for period in history.periods:
if period.usage is None:
print(period.period_start, '历史数据不完整')
else:
print(period.period_start, period.usage)
response = client.usage.current(
with_response=True, request_timeout=30.0, max_retries=2,
)
print(response.request_id, response.status_code, response.data)Python 默认返回 dataclass,通过属性访问字段;with_response=True 返回 SDKResponse。超时单位是秒。
异步调用:
import asyncio
import os
from lexmount import AsyncLexmount
async def main():
async with AsyncLexmount(
api_key=os.environ['LEXMOUNT_API_KEY'],
project_id=os.environ['LEXMOUNT_PROJECT_ID'],
base_url=os.environ['LEXMOUNT_BASE_URL'],
) as client:
current = await client.usage.current()
history = await client.usage.history()
print(current.usage, len(history.periods))
asyncio.run(main())JS/Python 默认请求超时为 30 秒、重试次数为 2(允许 0–5)。网络错误、超时及 HTTP 429/502/503/504 使用有界退避重试;其他状态不自动重试。对高频监控请自行设置合理采样间隔。
