GET /v1/balance

This read-only endpoint validates the API key but does not require a positive balance.

Request

curl https://api.model-gate.com/v1/balance \
  -H "Authorization: Bearer mg_live_..."

Response

{
  "object": "balance",
  "currency": "USD",
  "balance": "12.3400000000"
}

For Individual credentials, the balance belongs to the user that owns the key. For Business credentials, API charges always use the company owner wallet. The shared company balance is returned only when the credential principal has company-level balance visibility (organization owner, admin or billing role). Employee developer/viewer credentials may execute permitted API requests but receive HTTP 403 from /v1/balance; those users see only their allowed group usage and limits in the control panel. API-key usage and spend_limit remain separate values.

Authentication error

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "invalid API key"
  }
}

Business permission error

{
  "error": {
    "type": "permission_error",
    "code": "balance_not_permitted",
    "message": "Company balance is not available for this credential principal."
  }
}