2分で読めます

title: "使用量上限と警告" description: "Zenovayがプランに対して使用量をどう追跡し、80% / 95% で通知することで、突然上限に達することを防ぐ仕組みを説明します。"

使用量上限と警告

すべてのZenovay有料プランには、月次で追跡される3つのpay-as-you-go (PAYG) リソースがあります:

リソース	Free枠	カウント対象
ウェブイベント	プランにより異なる	ページビュー + カスタムイベント + ゴール
APIリクエスト	プランにより異なる	`ZV_*` APIキーで認証された呼び出し
First-Partyプロキシイベント	プランにより異なる	カスタムCF Workerプロキシ経由のイベント

これらのいずれかが**80%**を超えると、ダッシュボードに一度だけトーストが表示されます。**95%**で2回目のトーストが表示されます。期間中に警告が表示された後は、**翌カレンダー月の初日（UTC）**まで再度表示されません。

現在の使用量を読む

GET /api/billing/usage
Authorization: Bearer ZV_xxx

上限とパーセンテージ付きで現在の使用量を返します:

{
  "success": true,
  "data": {
    "websites": { "used": 2, "limit": 5, "percentage": 40 },
    "visitors": { "used": 18234, "limit": 100000, "percentage": 18 },
    "tier": { "name": "Pro 100K", "price": 35, "features": ["..."] },
    "period": {
      "start": "2026-04-01T00:00:00.000Z",
      "end":   "2026-04-30T00:00:00.000Z"
    }
  }
}

どの警告が既に発火したかを読む

GET /api/billing/usage-warnings?teamId=<team-uuid>
Authorization: Bearer ZV_xxx

{
  "success": true,
  "data": {
    "billing_period_start": "2026-04-01",
    "warnings_shown": {
      "events":       [80],
      "apiEvents":    [],
      "proxyEvents":  []
    }
  }
}

warnings_shown はリソースごとにキー付けされています。配列には、当該請求期間中に既に発火したパーセンテージしきい値（80 および/または 95）が含まれます。

プログラムで警告を確認済みにする

トーストが表示されたとき、ダッシュボードはこれを自動で行います。独自UIを構築する場合は、自前でPOSTすることもできます:

POST /api/billing/usage-warning-acknowledge
Authorization: Bearer ZV_xxx
Content-Type: application/json

{ "teamId": "<uuid>", "resource": "events", "threshold": 80 }

エンドポイントは冪等です — (team, period, resource, threshold) の組み合わせが既に記録されていても、200 OK が返されます。

100%到達時の挙動

プラン	100%到達時の挙動
Free	トラッキングが停止し、訪問者は `429` を受け取ります。継続するにはアップグレードが必要です。
Pro + Scale	PAYGが発動します（PAYG料金を参照）。トラッキングは継続され、超過分は月末に請求されます。
Enterprise	ソフトキャップ。アカウントマネージャーが事前に通知します。