用量与配额 API

这些端点返回的带宽数据与控制面板仪表盘上显示的完全一致：本计费周期内您已使用了多少套餐流量，以及还剩多少。对于 Residential Proxies，它们还会告诉您配额用完后会发生什么。

此外还有一个用量历史端点，用于查询任意时间窗口内的消耗量，而不是当前周期的用量。

身份验证

这三个端点均使用 api_token 查询参数进行身份验证。请在控制面板的 Account → API Tokens 中生成令牌。

?api_token=YOUR_API_TOKEN

账户端点和套餐端点的速率限制为每分钟 60 次请求，历史端点为每分钟 30 次。

账户用量

GET https://shifter.io/api/v1/user/usage

为每个有效套餐返回一个条目，并返回所有计量套餐的合计值。

令牌属于您本人，而不属于某一个工作区，因此返回结果既包含您自己的套餐，也包含您受邀加入的任何工作区中的套餐。响应会先列出这些工作区，并为每个套餐标注其所属的工作区；传入 workspace 可将结果限定为单个工作区。

参数	位置	必填	说明
`api_token`	query	yes	您的账户 API 令牌
`workspace`	query	no	工作区 ID，仅返回该工作区的套餐

示例：

curl "https://shifter.io/api/v1/user/usage?api_token=YOUR_API_TOKEN"

响应：

{
  "error": null,
  "code": 200,
  "data": {
    "totals": {
      "quota_bytes": 25000000000,
      "used_bytes": 12300000000,
      "remaining_bytes": 12700000000,
      "overage_bytes": 0,
      "quota_gb": 25,
      "used_gb": 12.3,
      "remaining_gb": 12.7,
      "overage_gb": 0,
      "used_percent": 49.2
    },
    "workspaces": [
      { "id": "qbz6", "name": "Personal", "role": "owner",  "personal": true,  "wallet_balance": 25.00 },
      { "id": "7dLm", "name": "Acme Inc", "role": "viewer", "personal": false, "wallet_balance": 0 }
    ],
    "memberships": [
      {
        "id": "aB3xY9",
        "plan": "Residential Proxies 25 GB",
        "service": "backconnect",
        "status": "Active",
        "metered": true,
        "quota_bytes": 25000000000,
        "used_bytes": 12300000000,
        "remaining_bytes": 12700000000,
        "overage_bytes": 0,
        "quota_gb": 25,
        "used_gb": 12.3,
        "remaining_gb": 12.7,
        "overage_gb": 0,
        "used_percent": 49.2,
        "resets_at": "2026-08-14T09:31:00+00:00",
        "overage_billed": true,
        "overage_rate_per_gb": 0.4,
        "wallet_balance": 25.00,
        "wallet_covers_gb": 62.5,
        "workspace": {
          "id": "qbz6",
          "name": "Personal",
          "role": "owner",
          "personal": true
        }
      },
      {
        "id": "kM7pQ2",
        "plan": "ISP Proxies 10 IPs",
        "service": "static-residential-proxies",
        "status": "Active",
        "metered": false,
        "quota_bytes": null,
        "used_bytes": null,
        "remaining_bytes": null,
        "overage_bytes": null,
        "quota_gb": null,
        "used_gb": null,
        "remaining_gb": null,
        "overage_gb": null,
        "used_percent": null,
        "resets_at": null,
        "overage_billed": false,
        "overage_rate_per_gb": null,
        "wallet_balance": 0,
        "wallet_covers_gb": null,
        "workspace": {
          "id": "7dLm",
          "name": "Acme Inc",
          "role": "viewer",
          "personal": false
        }
      }
    ]
  }
}

工作区

如果您受邀加入了他人的工作区，他们的套餐会与您自己的套餐一起显示在这里。workspaces 数组列出您的个人工作区以及您作为成员加入的每一个工作区，每个套餐的 workspace 字段下也带有相同的对象：

字段	说明
`id`	工作区 ID，即 `workspace` 查询参数接受的值
`name`	工作区名称，您自己的工作区为 `Personal`
`role`	您在该工作区中的角色：`owner`、`admin`、`billing` 或 `viewer`
`personal`	您自己的工作区为 `true`
`wallet_balance`	该工作区钱包中的资金，以美元计

所有角色都可以读取用量，就像所有角色都可以在控制面板中查看套餐一样。

即使您进行了筛选，workspaces 也始终是完整列表，因此只需一次调用即可获知所有 ID：

curl "https://shifter.io/api/v1/user/usage?workspace=7dLm&api_token=YOUR_API_TOKEN"

套餐用量

GET https://shifter.io/api/v1/memberships/{membership}/usage

返回单个套餐的用量，即上文 memberships 数组中出现的同一对象，但不含 workspace 块。

{membership} 路径参数接受套餐标识符的两种形式：控制面板套餐页面上显示的 Membership ID（例如 68057），或套餐 URL 中的短代码，也就是这些响应中的 id 字段（例如 Rxqk）。两者指向同一个套餐。

此端点适用于您可以访问的任何套餐：您自己的套餐，以及您所属工作区中的任何套餐。

参数	位置	必填	说明
`membership`	path	yes	Membership ID 或短代码
`api_token`	query	yes	您的账户 API 令牌

示例：

curl "https://shifter.io/api/v1/memberships/68057/usage?api_token=YOUR_API_TOKEN"

响应：

{
  "error": null,
  "code": 200,
  "data": {
    "id": "aB3xY9",
    "plan": "Residential Proxies 25 GB",
    "service": "backconnect",
    "status": "Active",
    "metered": true,
    "quota_bytes": 25000000000,
    "used_bytes": 12300000000,
    "remaining_bytes": 12700000000,
    "overage_bytes": 0,
    "quota_gb": 25,
    "used_gb": 12.3,
    "remaining_gb": 12.7,
    "overage_gb": 0,
    "used_percent": 49.2,
    "resets_at": "2026-08-14T09:31:00+00:00",
    "overage_billed": true,
    "overage_rate_per_gb": 0.4,
    "wallet_balance": 25.00,
    "wallet_covers_gb": 62.5
  }
}

按时间范围查询用量

GET https://shifter.io/api/v1/memberships/{membership}/usage/history

上面两个端点回答的是“本计费周期的使用情况如何”。而这个端点回答的是“在这两个时间点之间我用了多少”，这是另一个问题：周期数据会在续订时重置，因此无法告诉您上周二或上个月的情况。

参数	位置	必填	说明
`membership`	path	yes	Membership ID 或短代码
`api_token`	query	yes	您的账户 API 令牌
`start`	query	yes	时间窗口的起点（包含）
`end`	query	yes	时间窗口的终点（不包含）

start 和 end 接受日期（2026-08-16）或完整的时间戳（2026-08-16T09:00:00）。仅有日期时表示当天零点，因此单独一天写作 start=2026-08-16&end=2026-08-17。时间窗口最短可为一小时，最长为 366 天。

示例：

curl "https://shifter.io/api/v1/memberships/68057/usage/history?start=2026-08-16&end=2026-08-17&api_token=YOUR_API_TOKEN"

响应：

{
  "error": null,
  "code": 200,
  "data": {
    "id": "aB3xY9",
    "start": "2026-08-16T00:00:00",
    "end": "2026-08-17T00:00:00",
    "bytes": 184699800000,
    "gb": 184.7,
    "upload_bytes": 8146690000,
    "download_bytes": 176553110000,
    "requests": 3775940
  }
}

如需按天绘制用量图表，请每天调用一次，并将每一天作为独立的时间窗口。合计值可以精确相加，因此一周的每日调用之和与一次跨越整周的调用得到的数字相同。

此端点的速率限制为每分钟 30 次请求，而不是另外两个端点的 60 次。

错误

状态码	含义
`400`	`start` 或 `end` 缺失、无法解析、顺序颠倒，或相隔超过 366 天
`503`	用量历史暂时不可用，请退避重试

字段

字段	说明
`id`	套餐的短代码，可与数字形式的 Membership ID 一样用于路径中
`plan`	产品名称，与控制面板中显示的一致
`service`	产品系列，例如 `backconnect`、`static-residential-proxies`、`scraping`
`status`	套餐状态，例如 `Active`、`Active Trial`、`Overdue`
`metered`	该套餐是否设有带宽配额
`quota_bytes` / `quota_gb`	当前计费周期可用的带宽：套餐包含的额度，加上您为该套餐购买的所有流量充值
`used_bytes` / `used_gb`	当前计费周期内截至目前已消耗的带宽
`remaining_bytes` / `remaining_gb`	配额减去用量，最低为零
`overage_bytes` / `overage_gb`	超出所含配额的用量，仍在配额内时为零
`used_percent`	用量占配额的百分比。出现超额用量时会超过 100
`resets_at`	ISO 8601 时间戳，表示周期更替、用量归零的时间
`overage_billed`	该套餐超出配额后是否从钱包扣费
`overage_rate_per_gb`	超出配额后每 GB 的费用，以美元计。不对超额用量计费的套餐为 `null`
`wallet_balance`	工作区钱包中的资金，以美元计
`wallet_covers_gb`	按该费率计算，余额大约可支付超出配额的多少 GB

不计量的套餐

ISP Proxies 和 Sneaker Proxies 不限流量，而 Web Scraping API 和 SERP API 套餐按请求数而非带宽计价。这些套餐会返回 "metered": false，各项数值为 null，而不是一个容易被理解为“已无剩余”的零。它们仍会被列出，因此账户响应能完整反映您拥有的全部套餐。

超出配额后

Residential Proxies 不会在达到上限时停止：超出部分的用量会按每 GB 费率从您的工作区钱包扣费，因此只要钱包中有资金，套餐就会继续工作。overage_rate_per_gb 就是该费率，wallet_covers_gb 则是当前余额按该费率大约还能支撑多少流量，是在 remaining_gb 之外的一个粗略续航估算。

该费率是您的实际费率：套餐价格除以套餐配额，并已计入您享有的任何优惠券或折扣。它与控制面板套餐页面上 Overage rate 下显示的数字相同，也是计费任务扣费时使用的费率。

有几点值得了解：

钱包是按工作区设置的，而不是按套餐。如果您运行多个 Residential 套餐，每个套餐上的 wallet_covers_gb 都假设全部余额用于该套餐，它们都是基于同一笔资金计算的。
在试用期间，overage_billed 为 false。试用在达到额度时会暂停而不是计费，因此没有可覆盖流量的数值。费率仍会给出，因为这是试用转为正式套餐后的费用。
在其他所有产品上，overage_rate_per_gb 为 null：这些套餐会在达到上限时停止，而不会对超出部分计费。
当余额降至零且配额用尽时，服务会暂停，直到您充值或周期续订。

用量重置

用量是在当前计费周期内累计的，而不是滚动的 30 天窗口。它会在 resets_at，即套餐续订时归零。

错误

状态码	含义
`401`	`api_token` 缺失或无效
`403`	该套餐位于您不属于的工作区中
`404`	未找到套餐
`429`	一分钟内超过 60 次请求，请退避重试

立即开始

代理

APIs

资源

用量与配额 API

身份验证

账户用量

工作区

套餐用量

按时间范围查询用量

错误

字段

不计量的套餐

超出配额后

用量重置

错误