RevKeen Docs
Api reference

Get current usage balance

Returns the current usage balance for a customer or subscription in the active billing period. Shows per-meter breakdown with included allowance, overage, estimated charges, and margin data.

Common errors

  • 400 invalid_request — malformed payload or failed validation.
  • 401 unauthenticated — missing, malformed, or revoked API key.
GET
/usage/balance

Authorization

apiKey
x-api-key<token>

Your RevKeen API key (powered by Unkey). Get it from Dashboard > Settings > API Keys. Use rk_sandbox_* for test mode and rk_live_* for production.

In: header

Query Parameters

subscription_id?string

Filter to a specific subscription

Formatuuid
customer_id?string

Filter to a specific customer by RevKeen ID

Formatuuid
external_customer_id?string

Filter to a customer by your external identifier

meter_id?string

Filter to a single meter

Formatuuid

Response Body

application/json

application/json

application/json

curl "https://api.revkeen.com/v2/usage/balance" \  -H "x-api-key: $REVKEEN_API_KEY"
{
  "object": "usage_balance",
  "meters": [
    {
      "meter_id": "mtr_abc123",
      "meter_name": "API Calls",
      "unit_name": "calls",
      "current_value": 1250,
      "included_quantity": 1000,
      "used_quantity": 1250,
      "remaining_included": 0,
      "overage_quantity": 250,
      "estimated_amount_minor": 2500,
      "total_cost_minor": 0,
      "margin_minor": 0,
      "currency": "usd",
      "period_start": "2026-03-01T00:00:00.000Z",
      "period_end": "2026-03-31T23:59:59.999Z"
    }
  ],
  "total_estimated_amount_minor": 2500,
  "total_cost_minor": 0,
  "currency": "usd"
}
{
  "error": {
    "message": "string",
    "type": "string"
  }
}
{
  "error": {
    "message": "string",
    "type": "string"
  }
}
Edit on GitHub