Get the wallet balance

GET/v1/balance

Returns the wallet balance, the funds held for messages in flight and what new sends may use.

Scope

balance:read

Request

Every request needs an API key in the Authorization header, and the key needs the scope the endpoint names.

GET /v1/balance

Responses

200 OK

ReturnsBalanceEnvelope

• dataBalanceRequired

  The balance.

Headers

• Cache-ControlstringRequired

  Responses are never cached.

• RateLimit-Limitinteger

  Requests per second your account may sustain.

• RateLimit-Remaininginteger

  Whole requests left in your account's bucket.

• RateLimit-Resetinteger

  Seconds until the bucket is full again.

• X-Request-IdstringRequired

  This request's ID, also given as request_id in error bodies. Quote it to support.

{  "data": {    "object": "balance",    "as_of": "2026-09-28T10:15:30.000Z",    "available": "15215.0000",    "balance": "15250.0000",    "currency": "NGN",    "held": "35.0000",    "low_balance_threshold": "1000.0000"  }}

Errors

Each code links to its page. Branch on the code, never on the title or detail.

• 401 Unauthorized
  • unauthenticated
• 403 Forbidden
  • insufficient_scope
  • ip_not_allowed
• 413 Content Too Large
  • payload_too_large
• 415 Unsupported Media Type
  • unsupported_media_type
• 429 Too Many Requests
  • rate_limited
• 500 Internal Server Error
  • internal_error
• 503 Service Unavailable
  • service_unavailable

Code samples

Each sample reads your key from the API_KEY_500CALLS environment variable.

curl 'https://api.messaging.500calls.com/v1/balance' \  -H "Authorization: Bearer $API_KEY_500CALLS"

import osimport requestsresponse = requests.get(    "https://api.messaging.500calls.com/v1/balance",    headers={        "Authorization": f"Bearer {os.environ['API_KEY_500CALLS']}",    },    timeout=30,)print(response.status_code, response.json())

const response = await fetch("https://api.messaging.500calls.com/v1/balance", {  headers: {    Authorization: `Bearer ${process.env.API_KEY_500CALLS}`,  },});console.log(response.status, await response.json());

<?php$curl = curl_init('https://api.messaging.500calls.com/v1/balance');curl_setopt_array($curl, [    CURLOPT_HTTPHEADER => [        'Authorization: Bearer ' . getenv('API_KEY_500CALLS'),    ],    CURLOPT_RETURNTRANSFER => true,]);$body = curl_exec($curl);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);echo $status, PHP_EOL, $body, PHP_EOL;