利用枠とレート制限

利用には2種類の制限があります。プランで許可される1日あたりの検索回数と、リクエストを送信できる速さです。どちらもすべてのレスポンスで通知されるため、クライアントはわざとエラーを起こして限界を探らなくても、送信ペースを調整できます。

レート制限：1分あたり10リクエスト

この制限はアカウント単位で、APIとMCPサーバーで共有されます。どちらから呼び出しても、1分間に10回までです。この時間枠内の11回目のリクエストには、すぐに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ではそれが起こります（拒否するまで1秒ずつ最大30秒待機します）。これがAPIを用意した理由の1つです。

1日の利用枠

プランごとに、1日あたりの検索回数とスニペットリクエスト数が決まっており、別々にカウントされます。どちらも、使用から24時間後ではなく、次のUTC午前0時にリセットされます。

• 検索1回につき、検索の利用枠を1消費します。
• snippets=1を指定した検索は、代わりにスニペットの利用枠を1消費します。
• /v1/accountは何も消費しません。

利用枠を使い切ると、リクエストは429 quota_exceededまたは429 snippet_quota_exceededで拒否され、上限、使用量、リセットまでの時間が返されます。スニペットの利用枠を使い切っても、通常の検索は引き続き行えます。

結果の範囲

プランによって、ランキングのどの順位までの結果が表示されるかも決まります。これは/v1/accountのdisclosed_positionsで確認できます。それより下の行は空欄にされるのではなく除外され、除外された行がある場合は、本文のtruncatedがtrueになり、ヘッダーにX-Truncated: trueが付きます。

これがAPIとウェブサイトの最も重要な違いです。ブラウザでは、利用枠を使い切ると自動的に無料プランの範囲に切り替わって表示件数が減ります。人がページを見るぶんにはそれで問題ありません。しかしスクリプトにはそれがわからないため、APIでは結果を短くする代わりにリクエストを拒否します。

現在の状態の確認

認証済みのすべてのレスポンスには、5つのヘッダーが付きます。

検索結果には、さらに3つのヘッダーが付きます。

利用状況

/v1/accountを1回呼び出せば、すべての状況を確認できます。何も消費しません。

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をお使いください。