Gateway Stats

Endpoint

GET https://api.bve.me/admin/stats
Authorization: Bearer admin_bve_YOUR_ADMIN_KEY

Returns a real-time aggregate snapshot of the gateway: API key counts grouped by lifecycle status, cumulative request and token totals for the current and previous calendar months across all keys, and per-isolate request counter diagnostics for monitoring cap proximity.

This is a low-cost read — it runs a single batched D1 query (GROUP BY status, SUM for the current month, and SUM for the prior month) and returns immediately. No per-key data is exposed.

Authentication

Admin Bearer token required. See Admin API Overview for authentication details.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "keys": {
    "active": 12,
    "suspended": 1,
    "revoked": 3,
    "expired": 2,
    "expiring_soon": 1,
    "total": 18
  },
  "current_month": {
    "period": "2026-05",
    "total_requests": 48312,
    "total_tokens": 9204810
  },
  "previous_month": {
    "period": "2026-04",
    "total_requests": 41200,
    "total_tokens": 7830400
  },
  "isolate": {
    "month": "2026-05",
    "request_count": 1042,
    "soft_cap": 8500000,
    "hard_cap": 9500000,
    "soft_cap_exceeded": false,
    "hard_cap_exceeded": false
  }
}

Response fields

Field	Type	Description
keys.active	integer	Number of API keys with status active and a non-past expiry date (truly functional keys)
keys.suspended	integer	Number of API keys with status suspended
keys.revoked	integer	Number of API keys with status revoked
keys.expired	integer	Number of active-status keys whose expires_at is in the past. These keys return 401 api_key_expired on every request.
keys.expiring_soon	integer	Number of active-status keys whose expires_at is within the next 7 days. Useful for proactive rotation alerts.
keys.total	integer	Sum of active + suspended + revoked + expired
current_month.period	string	Current billing month in YYYY-MM format
current_month.total_requests	integer	Total requests recorded in D1 for this month across all keys
current_month.total_tokens	integer	Total tokens (prompt + completion) recorded in D1 this month
previous_month.period	string	Prior calendar month in YYYY-MM format (e.g. "2026-04" when current month is "2026-05")
previous_month.total_requests	integer	Total requests recorded in D1 for the prior month across all keys
previous_month.total_tokens	integer	Total tokens (prompt + completion) recorded in D1 for the prior month
isolate.month	string	Month the per-isolate counter covers (YYYY-MM). Resets when the month changes or the isolate is recycled.
isolate.request_count	integer	Number of requests this Worker isolate has handled this month. Per-isolate — not a global cluster total.
isolate.soft_cap	integer	MONTHLY_WORKER_REQUEST_SOFT_CAP env var value. 0 means disabled.
isolate.hard_cap	integer	MONTHLY_WORKER_REQUEST_HARD_CAP env var value. 0 means disabled.
isolate.soft_cap_exceeded	boolean	true if request_count >= soft_cap and soft cap is enabled. Triggers a console.warn log entry.
isolate.hard_cap_exceeded	boolean	true if request_count >= hard_cap and hard cap is enabled. Triggers 503 capacity_exceeded for subsequent requests.

Note

current_month.total_requests and total_tokens reflect what has been written to the monthly_usage D1 table. Requests that complete within the current Worker isolate’s execution window but whose D1 write is still pending in waitUntil may not appear immediately. The counts are eventually consistent, typically within seconds.

Per-isolate counter vs. global billing total

isolate.request_count tracks requests only within the specific Worker isolate that served this /admin/stats call. Cloudflare runs multiple isolates in parallel across its edge network — each has its own independent counter. The sum of all per-isolate counters represents total cluster traffic, but no single isolate sees the full total. Use current_month.total_requests (D1-backed) for billing-accurate totals, and isolate.request_count only to check cap proximity on a per-isolate basis.

cURL example

curl https://api.bve.me/admin/stats \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Common errors

Status	Code	Cause
401	missing_api_key	No Authorization header
401	invalid_api_key	Admin key does not match the configured ADMIN_API_KEY secret

Use cases

Dashboard summary card — key count and current-month burn:

curl -s https://api.bve.me/admin/stats \
  -H "Authorization: Bearer $ADMIN_KEY" | jq '.'

Alert when monthly token consumption exceeds a threshold:

const res = await fetch("https://api.bve.me/admin/stats", {
  headers: { Authorization: `Bearer ${adminKey}` },
});
const stats = await res.json();
const { total_tokens } = stats.current_month;
if (total_tokens > 1_000_000) {
  console.warn(`High token usage this month: ${total_tokens.toLocaleString()}`);
}

Month-over-month request and token trend:

const res = await fetch("https://api.bve.me/admin/stats", {
  headers: { Authorization: `Bearer ${adminKey}` },
});
const stats = await res.json();
const { current_month, previous_month } = stats;

const reqDelta = current_month.total_requests - previous_month.total_requests;
const tokenDelta = current_month.total_tokens - previous_month.total_tokens;
console.log(`Requests: ${previous_month.period} → ${current_month.period}: ${reqDelta >= 0 ? '+' : ''}${reqDelta}`);
console.log(`Tokens:   ${previous_month.period} → ${current_month.period}: ${tokenDelta >= 0 ? '+' : ''}${tokenDelta}`);

Check isolate cap proximity:

const res = await fetch("https://api.bve.me/admin/stats", {
  headers: { Authorization: `Bearer ${adminKey}` },
});
const { isolate } = await res.json();

if (isolate.soft_cap_exceeded) {
  console.warn(`Isolate soft cap reached: ${isolate.request_count}/${isolate.soft_cap}`);
}
if (isolate.hard_cap_exceeded) {
  console.error(`Isolate hard cap reached — new requests are returning 503 capacity_exceeded`);
}

When MONTHLY_WORKER_REQUEST_SOFT_CAP and MONTHLY_WORKER_REQUEST_HARD_CAP are both 0 (disabled), the exceeded flags are always false and request_count still reflects actual isolate traffic.

Next steps

Key Quota Per-key real-time quota status (minute/day/month counters from the Durable Object)

Usage Statistics Per-key historical request and token data by day and month

Model Stats Per-model request counts, token sums, and latency from sampled logs

Endpoint Stats Per-endpoint request counts, latency percentiles, and error rates

Key Stats Per-key leaderboard — top keys by request count, tokens, and latency

Admin API: API Keys List all keys and view their configured limits

Admin API: Overview All admin endpoints in one table