Skip to content
SMSRay

Balance

Check how much you can send before you send it, and alert your team well before the balance runs out.

GET/sms/balance
https://api.smsray.in/api/sms/v1/sms/balance

Read your workspace balance, per-type rates, allowed message types and this API client's counters.

Request

Headers

Retrieve balance request headers
NameTypeRequiredRules
x-api-keystringrequiredYour secret key, ls_live_ followed by 48 hex characters.

Example request

curl https://api.smsray.in/api/sms/v1/sms/balance \
  -H "x-api-key: $SMSRAY_API_KEY"

Response

200

200 application/json
{
  "balance": 500.0,
  "rate": { "transactional": 1.0, "otp": 1.0, "promotional": 1.0 },
  "allowedTypes": ["transactional", "otp", "promotional"],
  "counters": { "sent": 120, "delivered": 110, "failed": 4 },
  "workspaceStatus": "active"
}

Response fields

Retrieve balance response fields
NameTypeRequiredRules
balancenumberrequiredWorkspace balance (NPR), shared by every API client in the workspace.
rateobjectrequiredYour workspace's per-segment rate for transactional, otp and promotional. Cost = rate × segments.
allowedTypesstring[]requiredMessage types this workspace may send. Others return 403 forbidden.
countersobjectrequiredThis API client's own sent, delivered and failed totals.
workspaceStatusstringrequiredactive, pending or suspended.

Errors

Every error uses the same shape: { "error", "code", "details"? }. Branch on code, not on the message.

Retrieve balance errors
HTTPcodeWhen
401unauthorizedThe x-api-key header is missing ("Missing x-api-key") or the key is unknown ("Invalid API key").
403client_disabledThe API client that owns this key has been disabled in the dashboard.
429rate_limitedYou exceeded your per-client request rate (default 20 requests per second). Honour Retry-After.
500server_errorSomething went wrong on our side. The body never contains a stack trace.

Notes

  • GET requests keep working while your workspace is pending, so you can integrate and check your setup before activation.
  • Rates are set per workspace. Talk to us for your rate; the numbers in the example are placeholders.
  • A message's cost is refunded only when it finally fails (no route took it). undelivered is not refunded.