Key Stats

Endpoint

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

Returns a leaderboard of API keys with token totals, latency percentiles, and error breakdowns. Data is sourced from the 1%-sampled request_logs_sampled table. Default sort order is request_count descending; use sort_by and sort_dir to change it.

This is distinct from Usage Statistics (which returns exact D1-backed daily/monthly totals) and from API Key Quota (which returns real-time Durable Object counters). Key stats are sampled aggregates — useful for spotting traffic patterns across keys at a glance.

Sampling caveat

request_logs_sampled stores roughly 1 in every 100 requests. All counts are a statistical sample, not exact totals. Multiply by ~100 for an order-of-magnitude estimate of actual traffic. For exact per-key totals, use Usage Statistics.

Authentication

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

Query parameters

Parameter	Type	Required	Default	Description
model	string	No	—	Restrict stats to a single model ID. Only rows where request_logs_sampled.model = ? are counted. Keys with no rows for that model are excluded entirely.
endpoint	string	No	—	Restrict stats to a single endpoint path (e.g. /v1/responses). Only rows where request_logs_sampled.endpoint = ? are counted. Keys with no rows for that endpoint are excluded. Combines with model.
since	string	No	—	Include only log entries at or after this ISO 8601 timestamp
until	string	No	—	Include only log entries at or before this ISO 8601 timestamp
limit	integer	No	20	Maximum number of key rows to return (1–500)
sort_by	string	No	request_count	Column to sort by. One of: request_count, error_count, total_tokens, avg_latency_ms, max_latency_ms, p95_latency_ms
sort_dir	string	No	desc	Sort direction: asc or desc

All parameters are optional and combinable. Note: key_id filtering is not supported — use GET /admin/api-keys/:id/stats for a single key’s aggregate.

Response (200)

{
  "total": 2,
  "keys": [
    {
      "key_id": "550e8400-e29b-41d4-a716-446655440000",
      "key_name": "prod-client",
      "request_count": 412,
      "prompt_tokens": 540200,
      "completion_tokens": 148300,
      "total_tokens": 688500,
      "avg_latency_ms": 1340,
      "max_latency_ms": 9820,
      "p50_latency_ms": 1020,
      "p95_latency_ms": 6100,
      "error_count": 12,
      "client_error_count": 10,
      "server_error_count": 2,
      "error_rate": 2.91,
      "top_models": [
        { "model": "gpt-4o", "request_count": 218 },
        { "model": "claude-sonnet-4", "request_count": 89 },
        { "model": "gpt-4o-mini", "request_count": 45 }
      ]
    },
    {
      "key_id": "661f9511-f30c-52e5-b827-557766551111",
      "key_name": "ci-bot",
      "request_count": 54,
      "prompt_tokens": 12800,
      "completion_tokens": 4100,
      "total_tokens": 16900,
      "avg_latency_ms": 820,
      "max_latency_ms": 3140,
      "p50_latency_ms": 710,
      "p95_latency_ms": 2400,
      "error_count": 0,
      "client_error_count": 0,
      "server_error_count": 0,
      "error_rate": 0,
      "top_models": [
        { "model": "gpt-4o-mini", "request_count": 54 }
      ]
    }
  ]
}

Response fields

Field	Type	Description
total	integer	Total number of distinct keys in the result set (before limit is applied). Useful for pagination — if total > limit, not all keys are shown.
key_id	string	UUID of the API key
key_name	string	Human-readable name of the API key
request_count	integer	Number of sampled log entries for this key (~1% of actual requests)
prompt_tokens	integer	Sum of prompt tokens across all sampled entries for this key
completion_tokens	integer	Sum of completion tokens across all sampled entries. 0 for embedding-only keys.
total_tokens	integer	Sum of prompt_tokens + completion_tokens for each sampled entry
avg_latency_ms	number | null	Average end-to-end latency in milliseconds. null if no latency data was recorded.
max_latency_ms	number | null	Maximum end-to-end latency in milliseconds across all sampled requests for this key. Useful for spotting worst-case tail latency. null if no latency data was recorded.
p50_latency_ms	number | null	Median (50th percentile) latency in milliseconds
p95_latency_ms	number | null	95th percentile latency in milliseconds
error_count	integer	Number of sampled requests that returned HTTP 400 or above
client_error_count	integer	Number of sampled requests that returned HTTP 4xx
server_error_count	integer	Number of sampled requests that returned HTTP 5xx
error_rate	number	Error rate as a percentage: (error_count / request_count) × 100, rounded to 2 decimal places. 0 when request_count is 0.
top_models	array	Ordered list of the models most-used by this key, sourced from request_logs_sampled. Each entry has model (model ID string) and request_count (sampled count). Sorted descending by request_count. Empty array when the key has no model-bearing log rows.

cURL examples

Top 20 keys by request count

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

Top 10 keys in the last 24 hours

curl "https://api.bve.me/admin/key-stats?since=2026-05-25T00:00:00Z&limit=10" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Date-bounded key leaderboard

curl "https://api.bve.me/admin/key-stats?since=2026-05-01T00:00:00Z&until=2026-05-31T23:59:59Z" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Top keys by total token consumption

curl "https://api.bve.me/admin/key-stats?sort_by=total_tokens&limit=10" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Keys with the highest p95 latency

curl "https://api.bve.me/admin/key-stats?sort_by=p95_latency_ms" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Keys with the most errors this month

curl "https://api.bve.me/admin/key-stats?sort_by=error_count&since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Keys using a specific model

curl "https://api.bve.me/admin/key-stats?model=gpt-4o&limit=10" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Keys hitting a specific endpoint

curl "https://api.bve.me/admin/key-stats?endpoint=/v1/responses" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Combined filter — keys using gpt-4o on the Responses endpoint

curl "https://api.bve.me/admin/key-stats?model=gpt-4o&endpoint=/v1/responses&limit=5" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Pretty-print with jq

curl -s "https://api.bve.me/admin/key-stats" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  | jq '.keys[] | {key_name, request_count, total_tokens, error_rate}'

TypeScript example

const res = await fetch("https://api.bve.me/admin/key-stats?limit=10", {
  headers: { Authorization: `Bearer ${adminKey}` },
});

const { total, keys } = await res.json();

console.log(`Showing ${keys.length} of ${total} keys`);
for (const k of keys) {
  console.log(`${k.key_name} (${k.key_id}): ${k.request_count} sampled requests, ${k.total_tokens} tokens`);
}

Common errors

Status	Code	Cause
400	validation_error	since or until is not a parseable ISO 8601 timestamp
400	validation_error	sort_by is not one of the accepted column names
400	validation_error	sort_dir is not asc or desc
401	missing_api_key	No Authorization header
401	invalid_api_key	Admin key does not match the configured ADMIN_API_KEY secret

Use cases

Find which keys are consuming the most tokens this month:

curl -s "https://api.bve.me/admin/key-stats?sort_by=total_tokens&since=2026-05-01T00:00:00Z&limit=5" \
  -H "Authorization: Bearer $ADMIN_KEY"

Find the top consumers of a specific model:

curl -s "https://api.bve.me/admin/key-stats?model=gpt-4o&sort_by=total_tokens&limit=5" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  | jq '.keys[] | {key_name, request_count, total_tokens}'

Find which keys are hitting the Responses API:

curl -s "https://api.bve.me/admin/key-stats?endpoint=/v1/responses" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  | jq '.keys[] | {key_name, request_count}'

Find keys with a high error rate (potential misconfiguration):

curl -s "https://api.bve.me/admin/key-stats" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  | jq '[.keys[] | select(.error_rate > 10 and .request_count > 5)]'

Identify high-latency keys:

curl -s "https://api.bve.me/admin/key-stats?sort_by=p95_latency_ms" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  | jq '[.keys[] | select(.p95_latency_ms != null and .p95_latency_ms > 8000)]'

See which models each top key is using:

curl -s "https://api.bve.me/admin/key-stats?sort_by=total_tokens&limit=5" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  | jq '.keys[] | {key_name, total_tokens, top_models: [.top_models[] | "\(.model): \(.request_count)"]}'

Next steps

Per-Key Stats Single-key latency, token totals, and error breakdown with optional date filter

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

Usage Statistics Exact per-key request and token totals by day and month

Admin API: Overview All admin endpoints in one table