Model Stats

Endpoint

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

Returns request counts, token sums (prompt, completion, total), and latency aggregates grouped by model name. Data is sourced from the 1%-sampled request_logs_sampled table, so all figures reflect approximately 1% of actual traffic volume. Rows are ordered by request_count descending by default; use sort_by and sort_dir to change the order.

Sampling caveat

request_logs_sampled stores roughly 1 in every 100 requests. The counts returned by this endpoint 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
key_id	string	No	—	Restrict stats to a single API key UUID
provider	string	No	—	Filter by model creator. One of: anthropic, cohere, cursor, deepseek, google, meta, mistral, openai, wasikan. Returns 400 for any other value.
endpoint	string	No	—	Restrict stats to a specific gateway endpoint path (e.g. /v1/responses). Only rows where request_logs_sampled.endpoint = ? are aggregated; models with no rows for that endpoint are excluded. Combines with key_id and provider.
since	string	No	—	Include only log entries at or after this ISO 8601 timestamp. Invalid timestamps return 400 validation_error.
until	string	No	—	Include only log entries at or before this ISO 8601 timestamp. Combine with since for a bounded window.
limit	integer	No	50	Maximum number of model rows to return (1–500)
sort_by	string	No	request_count	Column to sort results by. One of: request_count, error_count, total_tokens, avg_latency_ms, max_latency_ms, p95_latency_ms. Returns 400 validation_error for unrecognized values.
sort_dir	string	No	desc	Sort direction: asc (ascending) or desc (descending). Returns 400 validation_error for other values.

All parameters are optional and combinable. For example, ?since=2026-05-01T00:00:00Z&sort_by=total_tokens&limit=10 returns the top 10 models by total tokens since May 1.

Response (200)

{
  "total": 12,
  "models": [
    {
      "model": "gpt-4o",
      "request_count": 142,
      "prompt_tokens": 184320,
      "completion_tokens": 62540,
      "total_tokens": 246860,
      "avg_latency_ms": 1240,
      "max_latency_ms": 8340,
      "p50_latency_ms": 980,
      "p95_latency_ms": 6200,
      "error_count": 3,
      "client_error_count": 2,
      "server_error_count": 1,
      "error_rate": 2.11,
      "top_endpoints": [
        { "endpoint": "/v1/chat/completions", "request_count": 120 },
        { "endpoint": "/v1/responses", "request_count": 22 }
      ]
    },
    {
      "model": "text-embedding-ada-002",
      "request_count": 89,
      "prompt_tokens": 44800,
      "completion_tokens": 0,
      "total_tokens": 44800,
      "avg_latency_ms": 120,
      "max_latency_ms": 580,
      "p50_latency_ms": 110,
      "p95_latency_ms": 340,
      "error_count": 0,
      "client_error_count": 0,
      "server_error_count": 0,
      "error_rate": 0,
      "top_endpoints": [
        { "endpoint": "/v1/embeddings", "request_count": 89 }
      ]
    }
  ]
}

Response fields

Field	Type	Description
total	integer	Total number of distinct model rows matching the current filters (ignores limit). When ?provider= is set, reflects the count after client-side provider filtering.
model	string	Model ID as returned by the upstream provider
request_count	integer	Number of sampled log entries for this model (~1% of actual requests)
prompt_tokens	integer	Sum of prompt tokens across all sampled entries for this model
completion_tokens	integer	Sum of completion tokens across all sampled entries. 0 for embedding models.
total_tokens	integer	Sum of prompt_tokens + completion_tokens for each entry
avg_latency_ms	number | null	Average end-to-end latency in milliseconds (rounded to integer)
max_latency_ms	number | null	Maximum end-to-end latency in milliseconds seen in the sample window
p50_latency_ms	number | null	Median (50th percentile) end-to-end latency in milliseconds. More representative than avg_latency_ms for skewed distributions.
p95_latency_ms	number | null	95th percentile end-to-end latency in milliseconds. Useful for understanding tail latency for SLO alerting.
error_count	integer	Number of sampled requests that returned HTTP 400 or above for this model.
client_error_count	integer	Number of sampled requests that returned HTTP 4xx (client errors: bad request, auth failure, rate limit, validation).
server_error_count	integer	Number of sampled requests that returned HTTP 5xx (gateway or upstream failures).
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_endpoints	array	Gateway endpoint paths this model was requested through, ordered by request_count descending. Each element has endpoint (string, e.g. /v1/chat/completions) and request_count (integer). The array is empty if no endpoint data was recorded.

avg_latency_ms, max_latency_ms, p50_latency_ms, and p95_latency_ms are null if no latency data was recorded for that model.

cURL examples

All models, last 50 by request count

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

Top 10 models in the last 7 days

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

Stats for a single key

curl "https://api.bve.me/admin/model-stats?key_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Filter by provider

# Only Anthropic models
curl "https://api.bve.me/admin/model-stats?provider=anthropic" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# Only OpenAI models, top 5 by request count
curl "https://api.bve.me/admin/model-stats?provider=openai&limit=5" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Filter by endpoint

# Only models used on the Responses API
curl "https://api.bve.me/admin/model-stats?endpoint=/v1/responses" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

# OpenAI models used on the Responses API, top 5 by request count
curl "https://api.bve.me/admin/model-stats?endpoint=/v1/responses&provider=openai&limit=5" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Sort by total tokens (descending)

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

Sort by p95 latency (ascending — fastest models first)

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

Sort by error count, limited to a provider

curl "https://api.bve.me/admin/model-stats?sort_by=error_count&provider=anthropic" \
  -H "Authorization: Bearer admin_bve_YOUR_ADMIN_KEY"

Pretty-print with jq

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

TypeScript example

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

const { models } = await res.json();

for (const m of models) {
  console.log(`${m.model}: ${m.request_count} sampled requests, ${m.total_tokens} tokens`);
}

Common errors

Status	Code	Cause
400	validation_error	since or until is not a parseable ISO 8601 timestamp
400	validation_error	provider is not one of the recognized provider values
400	validation_error	sort_by is not one of the recognized 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 models are consuming the most tokens:

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

Detect models with the worst tail latency:

curl -s "https://api.bve.me/admin/model-stats?sort_by=p95_latency_ms&limit=10" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  | jq '[.models[] | select(.p95_latency_ms != null) | {model, p95_latency_ms, avg_latency_ms}]'

Find models with the most errors:

curl -s "https://api.bve.me/admin/model-stats?sort_by=error_count&limit=5" \
  -H "Authorization: Bearer $ADMIN_KEY" | jq '.models[] | {model, error_count, error_rate}'

Find which models are used on a specific endpoint:

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

Compare model usage for a specific key over a date range:

curl -s "https://api.bve.me/admin/model-stats?key_id=<uuid>&since=2026-05-01T00:00:00Z&until=2026-05-31T23:59:59Z&sort_by=total_tokens" \
  -H "Authorization: Bearer $ADMIN_KEY" | jq '.'

Next steps

Request Logs Browse individual sampled log entries with per-request detail

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

Gateway Stats Gateway-wide key counts, monthly totals, and isolate diagnostics

Admin API: Overview All admin endpoints in one table