Skip to content
BVE Gateway BVE Gateway BVE Gateway

Usage Snapshot

GET /v1/usage returns a real-time snapshot of your API key’s request and token counters for all active quota windows. This call does not consume quota — it is exempt from RPM, RPD, and monthly limits. Use it to implement pre-emptive backoff or display usage dashboards before hitting a limit.

Endpoint

Section titled “Endpoint”
GET https://api.bve.me/v1/usage
Authorization: Bearer sk-bve-YOUR_KEY

Authentication

Section titled “Authentication”

Standard API key auth. Include your key as a Bearer token in the Authorization header.

Request

Section titled “Request”

No request body or query parameters.

Response

Section titled “Response”
{
  "object": "usage",
  "key_id": "3f7a2c1b-...",
  "key_name": "My Production Key",
  "status": "active",
  "expires_at": null,
  "is_expired": false,
  "last_used_at": "2026-05-27T09:00:00.000Z",
  "allowed_models": null,
  "this_minute": {
    "limit": 60,
    "used": 12,
    "remaining": 48,
    "resets_at": "2026-05-26T10:18:23.000Z"
  },
  "today": {
    "limit": 10000,
    "used": 843,
    "remaining": 9157,
    "resets_at": "2026-05-27T00:00:00.000Z"
  },
  "this_month": {
    "requests": {
      "limit": 5000,
      "used": 1247,
      "remaining": 3753,
      "resets_at": "2026-06-01T00:00:00.000Z"
    },
    "tokens": {
      "limit": 500000,
      "used": 83421,
      "remaining": 416579,
      "resets_at": "2026-06-01T00:00:00.000Z"
    }
  }
}

Response fields

Section titled “Response fields”
FieldTypeDescription
object"usage"Object type discriminator
key_idstringUUID of the authenticated API key
key_namestringDisplay name of the key (set at creation)
status"active" | "suspended" | "revoked"Current key status
expires_atISO 8601 | nullExpiry timestamp, or null if the key never expires
is_expiredbooleantrue when expires_at is set and the timestamp is in the past; false otherwise. Lets clients detect expired-but-status=active keys without comparing date strings.
last_used_atISO 8601 | nullTimestamp of the most recent authenticated request. Updated at most once per hour (hourly throttle in the auth middleware). null if the key has never been used.
allowed_modelsstring[] | nullStored model allow-list for this key. null or [] removes the per-key restriction; global policy and live availability still apply. New admin writes must use exact live Fuelix model IDs. Older keys may still return legacy wildcard prefixes until normalized.
this_minuteobjectCurrent RPM window
this_minute.limitnumberRequests allowed per minute (rpm_limit)
this_minute.usednumberRequests made in the current minute window
this_minute.remainingnumberRequests left before RPM limit is hit (clamped at 0)
this_minute.resets_atISO 8601UTC timestamp when the minute window resets
todayobjectCurrent RPD window
today.limitnumberRequests allowed per day (rpd_limit)
today.usednumberRequests made since last UTC midnight
today.remainingnumberRequests left before RPD limit is hit (clamped at 0)
today.resets_atISO 8601Next UTC midnight — when the day counter resets
this_month.requestsobjectMonthly request budget
this_month.requests.limitnumber | nullMonthly request cap (monthly_limit); null if not set
this_month.requests.usednumberRequests made this calendar month
this_month.requests.remainingnumber | nullRequests left; null when no monthly_limit is configured
this_month.requests.resets_atISO 8601First UTC second of next month
this_month.tokensobjectMonthly token budget
this_month.tokens.limitnumber | nullMonthly token cap (monthly_token_limit); null if not set
this_month.tokens.usednumber | nullTokens consumed this month; null when no monthly_token_limit is configured
this_month.tokens.remainingnumber | nullTokens left; null when no monthly_token_limit is configured
this_month.tokens.resets_atISO 8601First UTC second of next month

Null fields

Section titled “Null fields”

When a key has no monthly_limit configured, this_month.requests.limit and this_month.requests.remaining are null. When a key has no monthly_token_limit, all this_month.tokens fields except resets_at are null. The resets_at timestamps inside this_month are always present.

Examples

Section titled “Examples”
const res = await fetch('https://api.bve.me/v1/usage', {
  headers: { Authorization: 'Bearer sk-bve-YOUR_KEY' },
});


const usage = await res.json();


console.log(`RPM: ${usage.this_minute.used}/${usage.this_minute.limit} — resets at ${usage.this_minute.resets_at}`);
console.log(`RPD: ${usage.today.used}/${usage.today.limit}`);


if (usage.this_month.requests.limit !== null) {
  const pct = (usage.this_month.requests.used / usage.this_month.requests.limit * 100).toFixed(1);
  console.log(`Monthly requests: ${usage.this_month.requests.used}/${usage.this_month.requests.limit} (${pct}%)`);
}

Pre-emptive backoff pattern

Section titled “Pre-emptive backoff pattern”

Poll GET /v1/usage before making inference calls to avoid hitting limits mid-request:

async function checkQuotaBeforeRequest(threshold = 0.9): Promise<boolean> {
  const res = await fetch('https://api.bve.me/v1/usage', {
    headers: { Authorization: 'Bearer sk-bve-YOUR_KEY' },
  });
  const usage = await res.json();


  // Check RPM headroom
  const rpmPct = usage.this_minute.used / usage.this_minute.limit;
  if (rpmPct >= threshold) {
    const resetMs = new Date(usage.this_minute.resets_at).getTime() - Date.now();
    console.log(`RPM at ${(rpmPct * 100).toFixed(0)}% — waiting ${Math.ceil(resetMs / 1000)}s`);
    await new Promise(r => setTimeout(r, resetMs + 100));
    return false;
  }


  // Check monthly budget if configured
  if (usage.this_month.requests.limit !== null) {
    const monthPct = usage.this_month.requests.used / usage.this_month.requests.limit;
    if (monthPct >= 1) throw new Error('Monthly request budget exhausted');
  }


  return true;
}

Data sources and accuracy

Section titled “Data sources and accuracy”
CounterSourceNotes
this_minuteDurable ObjectExact; non-incrementing read (no side-effects)
todayDurable ObjectExact; resets at UTC midnight
this_month.requestsDurable ObjectExact per-month counter in the DO
this_month.tokensD1 (monthly_usage table)Aggregated; only present when monthly_token_limit is set; reflects tokens recorded before the current request (asynchronous)

The Durable Object read is a non-incrementing getUsage() call — it reads current state without modifying any counter. The monthly token total is read from D1 and is the same value used by the quota middleware for its pre-flight token check. Both sources are consistent with what the gateway enforces.

Errors

Section titled “Errors”
StatuscodeCause
401invalid_api_keyMissing or invalid Authorization header
401api_key_revokedKey has been revoked
401api_key_suspendedKey has been suspended
401api_key_expiredKey has passed its expires_at date

There is no 429 response for this endpoint — it bypasses all quota middleware.

Next steps

Section titled “Next steps”
Rate Limits & Quotas Full rate-limit header reference, Retry-After backoff patterns, and per-key limit configuration
Authentication Key format, statuses, and expiry
Admin API: API Keys Set rpm_limit, rpd_limit, monthly_limit, and monthly_token_limit on a key
Admin API: Key Quota Admin view of real-time RPM, RPD, and monthly quota state per key