我们使用 Cookie 来改善您的体验。

Cookie 政策
Logo of Lexmount
文档模板博客帮助中心
GitHub
Logo of LexmountLexmount Browser

开始使用

Lexmount 文档
控制台使用指南

Browser

Web Fetch

概览快速开始
常见错误

Web Search

概览快速开始搜索接口

运行时

概览快速开始
示例

帮助与计费

用量查询 API 与 SDK能力名词 FAQ
更新日志联系支持

用量查询 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_idstring查询的项目
as_ofstring查询时刻,RFC 3339 时间戳
timezonestring固定 Asia/Shanghai,配额周期计算时区
planstring当前生效套餐标识
period_start / period_endstring周期开始/结束时间戳,起点包含、终点不包含
usageobject已用量,见下表
limitsobject基础配额:browser_ms、webfetch_count、official_proxy_bytes
remainingobject剩余额度,同 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 / timezonestring与 current 对应字段含义相同
window_startstring查询时刻往前 365 天
retained_sincestring账本保留范围起点
accounting_basisstring固定 retained_reset_adjusted
periodsarray周期列表,最新在前

每个 period:

字段类型含义
period_start / period_endstring配额周期边界
planstring该段生效套餐标识
coveragestringretained 或 outside_retention
usageobject 或 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 使用有界退避重试;其他状态不自动重试。对高频监控请自行设置合理采样间隔。

示例

可复制运行的持久数据库、对象与 KV 存储、HTTP 服务、远程客户端和云浏览器示例。

能力名词 FAQ

了解上下文持久化、自定义扩展、代理与文件下载等 Browser 套餐能力。

目录

可用性
鉴权与请求规则
GET /v1/usage/current
usage 计数
GET /v1/usage/history
错误与限流
Node.js SDK
Python SDK

问题没有解决?