配额与速率限制

有两项互相独立的限制：套餐每天允许的搜索次数，以及请求的到达速度。每个响应都会报告这两项的状态，因此客户端无需故意触发错误来摸清边界，就能自行控制节奏。

速率限制：每分钟十个请求

该限制按账户计算，由 API 和 MCP 服务器共享：无论通过哪种方式发起，每分钟最多十次调用。在时间窗口内的第十一个请求会立即返回 429 too_many_requests，并附带 Retry-After 响应头，告知还需多少秒才会空出名额。响应体中的 error.retry_after 也给出同一数值。

HTTP/2 429
Retry-After: 18

{ "error": { "code": "too_many_requests",
             "message": "At most 10 requests per minute.",
             "retry_after": 18 } }

等待 Retry-After 秒后重新发送请求即可。此次请求没有消耗任何资源，也没有扣除配额。

API 从不通过占住连接来拖慢您。旧版导出 URL 则会这样做：每次等待一秒，最长等待半分钟后才拒绝请求。这正是推出 API 的原因之一。

每日配额

您的套餐规定了每天的搜索次数和代码片段请求次数，两者分开计算，都在下一个 UTC 午夜重置，而不是在使用 24 小时后重置。

• 每次搜索消耗一次搜索配额。
• 带 snippets=1 的搜索改为消耗一次代码片段配额。
• /v1/account 不消耗配额。

配额用完后，请求会被拒绝并返回 429 quota_exceeded 或 429 snippet_quota_exceeded，其中包含限额、已用量以及距重置还有多久。代码片段配额用完不会影响普通搜索。

结果深度

套餐还决定了结果在排名中能显示到多深，即 /v1/account 中的 disclosed_positions。超出该位置的行会被直接略去，而不是留空；只要有行被略去，响应体中的 truncated 就为 true，响应头中则为 X-Truncated: true。

这是 API 与网站之间最重要的区别。在浏览器中，配额用完后会悄悄退回免费版的深度、显示更少的结果，这对浏览网页的人来说没有问题。但脚本察觉不到这种变化，因此 API 会直接拒绝请求，而不是缩减结果。

查看当前状态

每个经过身份验证的响应都带有五个响应头：

搜索结果还另外带有三个：

用量统计

/v1/account 一次调用即可获得完整信息，而且不消耗任何配额：

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "disclosed_positions_snippets": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

旧版的 https://publicwww.com/profile/api_status.xml?key=... 以 XML 报告同样的计数，目前仍然可用。它属于旧版 URL；新代码应使用 /v1/account，它不仅报告用量，还报告各项限额。